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Preface 

Intended Audience 

This manual is intended for all diagnostic programmers. 



Structure of This Document 

This manual contains six chapters: 

• Chapters 1 through 4 discuss the fundamentals of a VAX/DS diagnostic 
program. 

• Chapter 5 provides detailed reference information on each VAX 
Diagnostic Supervisor macro and system service. 

• Chapter 6 describes the necessary steps required to create a VAX/DS 
diagnostic program. 



Associated Documents 

Diagnostic program users will find the VAX/DS Diagnostic Supervisor 
User's Guide helpful. 

The following documents may also be useful: 

• VAX Diagnostic Software Handbook 

• VAXA^MS System Services Reference Manual 

• VAX/VMS I/O User's Guide 

• VAX Architecture Reference Manual 



Conventions Used in This Document 



Convention Meaning 



BOLD Introduces new terms. 

italics Used for emphasis and indicates the title of a manual. 

KEYWORD Keywords are capitalized. 

[ ] Square bracitets Indicate that the enclosed element Is 

optional. 
DS > LOAD EVXYZ.EXE Command examples show the VAX/DS prompt DS> . 
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•^ What Is a Diagnostic Program? 



1.1 Introduction 



This chapter presents an introduction to diagnostic program design. It 
discusses the uses and users of diagnostic programs, the testing goals any 
diagnostic program design should meet, and the various methods used to 
test hardware. It also discusses those characteristics which are common to 
all diagnostic programs, regardless of the hardware they are designed to 
execute in or test. 



1 .2 Uses of Diagnostic Programs 



1.3 Definitions 



A diagnostic program is any program designed specifically to discover and 
identify hardware failures in a computer system. Diagnostic programs are 
typically used in the following situations: 

• During execution of applications or systems programs, the system 
produces unexpected events or incorrect computation results. This 
indicates a malfunction, possibly hardware. 

• During the manufacturing stage, every device and system must be 
thoroughly tested before it is shipped to a customer. 

• During the product design stage, the functionality of a product must be 
verified. 



The following are some commonly used terms: 

• System under test (SUT). The hardware system on which a diagnostic 
program is executed. 

• Unit under test (UUT). The device tested (part of the SUT). The UUT is 
defined by the diagnostic program and can be one drive of a particular 
device 1)^6 or an entire subsystem of the SUT, such as one of the 
remote nodes of a host system. 

• Hardcore. The portion of the SUT's hardware that must operate 
properly for the diagnostic program to execute. Programs that 
test peripheral devices typically have a hardcore consisting of the 
processor, main memory, and a program load device. A program's 
hardcore should never include any portion of the UUT. 

• Field-replaceable unit (FRU). Any portion of the UUT that can be easily 
and quickly replaced at a customer's site (for example, a logic board). 
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What Is a Diagnostic Program? 



1.4 Users and Their Needs 



Diagnostic programs are used in a variety of environments, and therefore 
the users (operators) of these programs are also varied. When a diagnostic 
program is used to identify problems in a system at a customer site, 
the program may be run by a customer service representative or by the 
customer. Diagnostic programs used to verify devices and systems may be 
run by a technician at the manufacturing site. Diagnostics may be loaded 
and run using an automated method requiring no operator. New systems, 
upon arrival at a customer site, must be verified by a customer service 
representative. Design verification, via diagnostic programs, may be done 
by an engineer. 

Because of the diversity of users, it is important that the writers of 
diagnostic programs are aware of the users. Some programs are intended 
for a specific audience, allowing the program to be tailored. However, 
most programs are intended for a wide range of users and must be written 
so that they are useful to all of them. 

All users of diagnostic programs have specific needs that diagnostic 
programs must fulfill. One common goal for all users (customers, customer 
service representatives, technicians, engineers, etc.) is coverage, the abiUty 
to find as many failures as possible. Every user expects that if a fault exists 
on the device being tested, a diagnostic program will detect that fault. 

The most important goals for customers are: 

• Ease of use. The functions of diagnostic programs relate to internal 
system hardware, and therefore are very technical. Customers should 
not be required to understand all the operations which take place in the 
diagnostic program. Therefore, the human interface must be simple. 
For example, installing cables, setting switches on logic boards, and 
requesting information such as CSR addresses or device priority levels 
are all to be avoided if possible. 

• Preservation of user data. Since device media may contain data needed 
by the user, diagnostic programs must provide safeguards against 
destruction of this data. This is generally accomplished by writing only 
on media designated for diagnostic use. Some disks provide specific 
sectors that are used only for diagnostic purposes. 

• Usage of system during diagnosis. A large system at a customer site 
will usually be timeshared by many users. If the users cannot use the 
system while diagnostic programs are rurming, significant loss to the 
customer can occur. Therefore, diagnostic programs should operate 
under the user's operating system and not preempt other system users. 

The most important goals for customer service representatives are: 

• Quick fault detection. The faster a customer service representative 
arrives at a site, fixes the problem, and leaves, the happier the 
customer will be. 

• Identification of bad field-replaceable units. The diagnostic program 
should be able to report to the customer service representative which 
FRU should be replaced. 
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• Good program documentation. To identify a failure, it is often 
necessary for the customer service representative to understand what 
functions a diagnostic program is performing. Therefore, the program 
should be well documented with detailed functional descriptions of 
each test. 

The goals of a manufacturing team depend on which phase of the 
manufacturing process a diagnostic program is used: 

• In the module test phase. Quick error detection is valued, particularly 
in high volume settings. Good error identification is sometimes 
unnecessary because modules are sent to module repair stations 

that use their own special-purpose hardware and software to identify 
module failures. In other cases, module repair stations are not used 
and good error identification is important. 

• In the device test phase. Manufacturing technicians have the same 
requirements as customer service representatives. Quick error 
detection is needed so the manufacturing process will not be slowed. 
Error identification of an easily replaced constituent part of the 
hardware system is necessary so the part can be replaced and the 
device shipped while the bad part is repaired, instead of holding up 
shipment of the device. Good documentation is necessary because 
determining the bad part sometimes requires a thorough understanding 
of the diagnostic program's functionality. 

The most important goal of design engineers is: 

• High coverage. Every section of the logic should be tested by the 
diagnostic. Any section that is not tested may contain a design flaw 
that may not be caught until after the hardware is in production, 
necessitating an engineering change order (ECO). 

It is important to note that user requirements often vary depending on the 
product. For example, program requirements specified by manufacturing 
personnel will depend on the manufacturing site's testing strategy for the 
product. This strategy is often not the same for different products. The 
program developer must maintain close communication with the program's 
eventual users in order to meet the needs of those users. 

1.5 Run-Time Environments 

The variety of uses and users of diagnostic programs creates a variety of 
"run-time environments" in which diagnostic programs must be able to 
execute. A run-time environment is the control-level software on which the 
diagnostic program must run. Some diagnostic programs cannot function 
in all run-time environments. The environments in which a program is 
designed to run are determined by the purpose the program is to serve. 

In the "user mode" run-time environment, a timesharing operating system 
is executing on the system tested. There could be many users on the 
system at the time a diagnostic program is run, and the diagnostic program 
is just another user of the system. Tlie diagnostic program should not 
affect any other user on the system. (Tlie operating system will prohibit 
the diagnostic program from exceeding its bounds.) Often, the device 
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tested is assigned exclusively to the diagnostic program, and the device's 
storage medium must be replaced with a "scratch" medium the diagnostic 
program can use to write test patterns. Some storage devices provide an 
area for the exclusive use of diagnostic programs, such as the "maintenance 
cylinders" on some disk media. In such cases, the diagnostic program uses 
this reserved area and other users of the device are unaffected. 

The opposite of the user mode run-time environment is the "standalone 
mode" environment. In standalone mode, the diagnostic program has 
exclusive use of the computer system. There is no high-level operating 
system to allow other users to run at the same time or to place execution 
boundaries on the diagnostic program. Thus, the diagnostic program 
can run in privileged execution modes and use reserved registers and 
memory space. Sometimes in standalone mode a monitor or other type 
of control program provides services to and controls execution of the 
diagnostic program. However, this type of monitor will not place execution 
constraints on the diagnostic program. 

The advantage of standalone mode over user mode is that the lack of 
execution boundaries sometimes offers a greater level of resolution in 
error identification. The disadvantage is that the computer's operating 
system must be brought down, costing the customer time and money. This 
disadvantage does not exist when these programs are used on new systems 
at the manufacturing site. 

This description of user and standalone modes implies that the computer 
system under test is not connected to another system by means of any 
type of network used for system diagnosis. However, there are networks 
that are used to load and run diagnostic programs, increasing the number 
of run-time environments with which to be contended. Networks are 
commonly used at manufacturing sites, where it is necessary to test a large 
number of systems at once. Typically, a host processor will maintain up- 
to-date copies of all diagnostic programs. The system to be tested will be 
connected to the host, and the host will transmit the appropriate programs 
to the test system. The programs will be executed in the test system's 
processor, but the host will monitor the performance of the programs and 
note any errors that occur. 

Networks can also be used to diagnose systems at customer sites. 
In this case, a centrally located host system can use phone lines to 
"call" a customer's system. The host can then monitor diagnostic 
programs executed on the system tested and provide customer service 
representatives with the results of the tests. This can greatly decrease the 
amount of time customer service personnel must spend at the customer's 
site; because they will not go to the customer site until after the tests are 
executed, they will have a good idea of what the problem is before they 
arrive. 
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1.6 Testing Goals 



All diagnostic programs have the same testing goals, regardless of what 
they test, what their execution environments are, or who the main users 
are. The goals are: 

• Clearly define the testing scope and required hardcore. The "testing 
scope" is that portion of the hardware logic which the program tests. 
It should never extend beyond the boundaries of the unit under test. 
For example, consider a disk controller that can support several drives. 
A diagnostic program to test the controller should not detect faults on 
the drives, unless it cannot be avoided. Signals generated in the logic 
should be limited to those areas meant to be tested by the diagnostic 
program. (The fewer stray signals there are in the system, the easier it 
will be to identify the failure.) 

The hardcore required by the diagnostic program should be as small 
as possible. Testing almost any peripheral device requires some 
correctly functioning logic that signals must pass through in order 
to get to and from the UUT. The smaller this hardcore, the more 
likely that a diagnosis of the UUT can be made without finding other 
errors within the the system but outside the scope of test, which could 
invalidate the diagnosis. For example, a program designer writing a 
diagnostic program for a disk might have the option of having memory 
management on or off while the program is running. Having memory 
management on will increase the hardcore for the diagnostic program, 
and the program will not be able to test the disk if there are errors in 
the memory management logic. 

• Detect any and all failures that could occur within the testing scope. 
If any part of the unit under test could malfunction, the diagnostic 
program should be able to detect that malfunction. The diagnostic 
prograni does NOT need to be concerned with problems outside the 
scope of the unit it is intended to test. For example, a diagnostic to 
test a disk driver should not be expected to detect CPU problems 
(although it might detect them inadvertently). This goal is clear-cut and 
simple — if a malfunction occurs an)Avhere within the unit under test, ^ 
the diagnostic program should detect and report it. Thus, a diagnostic 
program designed to test a set of tape drive controllers and their 
attached drives should be able to detect any failure occurring in either 
the controllers or their associated drives. A system exerciser (designed 
to validate the overall functionality of a computer system, including 
the CPU, memory, and all peripheral devices) should be able to detect 
errors on any device attached to the system. 

• Identify which part of the unit under test caused the malfunction. It is 
not enough to recognize that an error has occurred. The diagnostic 
program should also be able to indicate which part needs to be 
repaired or replaced. 

This third goal is not as clear-cut as the last one, for it involves the 
concept of "degree of resolution." When attempting to identify a 
failing part, the diagnostic program designer must decide what the 
smallest part within the system is that should be considered. Each 
computer system is made up of hardware devices, which contain one 
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or several logic boards, which in him are made up of IC chips. A 
diagnostic program's degree of resolution is a relative measure of its 
ability to identify the smallest possible failing constituent part. For 
example, consider a tape subsystem consisting of several tape drives 
connected to one controller. A diagnostic program that could identify 
the failing logic board within the failing tape drive would have a higher 
degree of resolution than one that only identified the failing drive. 
("Fault isolation" is another phrase often used to refer to the degree of 
error resolution.) 

A particular program's proper degree of resolution depends on its 
intended function. For example, it would be impractical for a system 
exerciser (described in Section 1.7) to attempt to identify failures to 
the degree of the failing chip. More likely, it would determine which 
peripheral device was malfunctioning and, if the peripheral consisted 
of several drives attached to one controller, which drive was in error. 
On the other hand, a diagnostic program designed to test a specific 
peripheral device probably should attempt to identify the failing logic 
board within that device. 

A diagnostic program's degree of resolution can also be affected 
by the program's user requirements. It is not always practical to 
achieve the highest possible degree of resolution, because increasing 
resolution can also cause increased program size and run-time, and 
may require a more highly skilled operator. In some cases, it may be 
more important to keep these variables within bounds than to attain a 
high degree of resolution. Unfortunately, achieving a high degree of 
error resolution is sometimes more an ideal than an attainable goal. 
Diagnostic programs used by customer service representatives should 
ideally be able to identify the smallest malfunctioning FRU. But for 
the program to identify an error as existing on one particular FRU, 
two requirements must be met. First, all the hardware logic used to 
execute the function that failed must reside on a single FRU. Second, 
the diagnostic program must be able to determine on which FRU the 
logic resides. Both these requirements can only be met through proper 
hardware design of the device. Close communication between the 
hardware designer and the diagnostic program designer aie essential 
when a new product is in development; this guarantees proper logic 
partitioning along with visibility of all signals needed by the program to 
achieve high error resolution. 

Provide enough useful program loops so that all possible errors can be 
quickly and easily detected by observing logic state transitions. It is 

sometimes not possible for a diagnostic program to accurately identify 
a failure to the degree of resolution desired in a particular situation. In 
these cases a technician will have to determine the failing component 
by examining electrical signals on logic boards with an oscilloscope. 
The responsibility of the diagnostic program then is to provide the 
technician with aids to locate the failure quickly and accurately. These 
aids mainly consist of program loops that can be invoked if an error is 
detected, and whose purpose is to provide repetitive state transitions 
on small subsets of the hardware logic so that the technician can easily 
observe these transitions and make sure they are taking place properly. 
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1 .7 Logic Tests, Function Tests, and Exercisers 



Not all diagnostic programs have the same functional goals. In general, 
diagnostic programs can be divided into three groups: logic tests, function 
tests, and exercisers. 

A logic test verifies the device's combinational logic, i.e., confirms that a 
section of hardware logic within the device is functioning correctly. This 
type of test should provide the greatest degree of error resolution. Logic 
tests are usually used during the repair of a failing device, and are designed 
to run in a standalorie environment. 

A function test verifies the functionality of a device. For example, a 
function test for a disk drive would be used to verify that the functions 
provided by the disk, such as reading and writing blocks of data, are 
operating properly. These tests may not have as great a degree of error 
resolution as logic tests. Function tests may be used to detect failures and 
during the repair of failing devices. Function tests can be designed to run 
in either a standalone or user mode environment. 

An exerciser is used to verify that a system's functionality can be sustained 
over a period of time. They are t3rpically designed for use on an entire 
system rather than on a single device. An exerciser will simultaneously 
perform repeated functional testing of every device composing the system, 
in an attempt to detect both failures which result from simultaneous use of 
numerous devices and failures which only occur intermittently. 

For many products, both a logic test and a function test are developed. 
The function test is used to detect the hardware failure and the logic test 
is used during repair of the failing part. Some products have logic tests in 
microprograms (see Section 1.10). The diagnostic program requirements 
for every product will vary; therefore, it is important to discuss these 
requirements with the program users. 



1 .8 Serial and Parallel Testing 



Many diagnostic programs are designed to test all existences of a specific 
type of device on a given system. There are two methods by which this 
testing of multiple units can be accomplished: serial testing and parallel 
testing. Serial testing involves testing each unit of the device individually, 
sequentially. Parallel testing is the testing of all units simultaneously.Serial 
testing is more likely to be found in a logic test, where it is desirable to 
keep the overall level of system activity to a minimum. Parallel testing is 
usually used in function tests to achieve higher levels of system activity. 



1 .9 Bottom-Up and Top-Down Testing 



Two testing techniques, bottom-up and top-down, are used to test hardware 
systems. They are generally used in combination to produce a thorough 
test of the UUT. 
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Bottom-up testing involves testing a device or system by considering the 
UUT to be made up of a set of layers of component parts. The lowest 
layer of component parts is the simplest and most elementary. Higher 
layers depend on the proper functioning of the component parts contained 
within lower layers. The simplest layer (lowest layer) is tested first; as a 
layer passes the testing, it is added to the hardcore for the next layer. This 
testing technique is based on a "guilty until proven innocent" assumption, 
i.e., a section of hardware is not assumed to be functioning properly 
("innocent" of causing errors) until its integrity is verified. 

Bottom-up testing is an integral part of logic tests. The logic must be 
tested in an order such that all of the logic, through which electrical signals 
must pass before reaching the logic being tested, has previously been 
tested. Each section of logic is viewed as another layer which depends 
on the previous sections or layers operating properly. Function tests 
also use bottom-up testing. For example, a diagnostic program for a disk 
should verify data reads before verif3dng data writes, since the data which 
was written can not be checked unless the data can be read correctly. 
The bottom-up technique provides a thorough, systematic, step-by-step 
approach to hardware testing. However, using this method to validate an 
entire system can be very slow. 

Top-down testing consists of initially viewing the UUT as a whole, then 
gradually subdividing the UUT into its component parts until the failing 
part can be identified. This technique uses an assumption of "innocent 
until proven guilty." The program assumes everything is operating 
properly unless errors are detected. An important consideration with 
this approach is that a fault might exist in a portion of the hardware outside 
the testing scope of the diagnostic program. In this case, the diagnostic 
program might not detect or might incorrectly diagnose the error, or might 
not be able to execute at all. 

In practice, diagnosis of a hardware system suspected of containing 
faults combines top-down and bottom-up techniques. Often, bottom- 
up programs will be run in a top-down manner; i.e., programs written to 
use the bottom-up technique are run in an order such that those which 
test the largest subsystems are executed first, followed by those which test 
devices which previously executed programs point out as questionable. 



1.10 Macroprograms and Microprograms 



Many computer processors built today have two types of programming 
instructions. "Macro-instructions" make up the processor's machine 
language. These instructions are the "moves," "branches," arithmetic and 
boolean operators, and so on, that are used to manipulate data in specific 
memory locations. Programs that use these instructions, either directly 
through the use of an assembly language or indirectly by using a high-level 
language compiled to an assembly language, are called "macroprograms." 
Most programs written are macroprograms. 

Beneath the macro-instructions is a set of "micro-instructions" used to 
implement the processor's machine language. Micro-instructions define 
the macro-level instructions, plus the registers defined by the machine 
language as existing "in the processor" (such as general-purpose registers 
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or a program counter). Micro-instructions do not execute in the system's 
main memory. Instead, they are loaded into and executed in a writable 
control store (WCS). (Micro-instructions also often exist in ROMs.) Since 
micro-instructions execute more rapidly than macro-instructions, it is 
sometimes useful for applications or systems programmers to use the 
micro-instruction set to create "microprograms." 

Developers of diagnostic programs sometimes make use of micro- 
programming. Programs designed to test the processor will most likely 
use micro-instructions, executing them in a WCS. Some peripheral devices 
possess their own microprocessors. These devices usually also have 
ROMs in which diagnostic routines have been stored. In this case the 
diagnostic programmer writes a macrodiagnostic program that activates the 
microprograms residing in the ROM. 

Parts of Chapter 2 discuss diagnostic microprograms further. However, 
most of this manual concerns diagnostic macroprograms. 
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2.1 Introduction 

The discussion in Chapter 1 consisted of an overview of diagnostic 
programs. It did not address specific types of computer systems. This 
chapter introduces characteristics of diagnostic programs that are unique to 
VAX. 

2.2 Run-Time Environments for VAX Diagnostic Programs 

VAX diagnostic programs are expected to operate in several run-time 
environments. These include user mode, standalone mode, and network 
environments. 

The user mode environment that supports execution of VAX diagnostic 
programs is the VAXA^S operating system. For almost all devices 
supported by DIGITAL under VAX/VMS, a user mode diagnostic program 
must be developed. These programs are used extensively at customer sites 
so that diagnostic programs can be executed without bringing down VMS 
and thus locking other users out of the system under test. 

Many VAX diagnostic programs are designed to execute in standalone 
mode. Manufacturing sites commonly use standalone programs in order to 
elimiimte the need to boot VMS just to run the diagnostic programs. Since 
standalone programs often provide better error detection than user mode 
programs, customer service personnel sometimes must use standalone 
programs at customer sites. Repair of failing device parts (after they have 
been identified and removed from the system under test) almost always 
involves the use of standalone diagnostic programs. 

Networking environments have been developed for loading and executing 
diagnostic programs on VAX computer systems. One example is the 
Automated Product Test (APT) run-time environment, commonly used 
at manufacturing sites. Under this environment, a system under test is 
cormected to a "mother" system that has copies of all diagnostic programs 
used. For each system to be tested, a "script" is built. A script is a file 
containing a list of diagnostic programs to be run, along with any run-time 
parameters that must be passed to the diagnostic program. The mother 
system reads this script and sends the appropriate diagnostic programs, 
one at a time, to the system under test. (This is referred to as "down-line 
loading.") Once a progrsim has been sent to the system under test, it is 
started eind monitored by the mother system, which will note any errors 
detected. When one program has completed execution, the next one listed 
in the script is sent down the line and started, until all programs in the 
script have been run. Programs executing on the system under test can 
only run in standalone mode. 
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Another example of a diagnostic network is APT/RD (for Remote 
Diagnosis), which provides a method of loading and monitoring diagnostic 
programs for diagnosing a system at a customer site. With APT/RD, a 
temporary communications link (via phone lines) is established between 
the system to be tested and a centrally located system belonging to 
DIGITAL and running the APT/RD software. Once the link is established, 
the central system can step through a script of diagnostic programs to 
attempt to diagnose the customer's system. Unlike the APT system used 
at manufacturing sites, though, the APT/RD system usually does not 
perform down-line loading of diagnostic programs. Instead, the programs 
must exist on some storage medium of the customer's system. They are 
loaded "locally" from that medium, on command from the central system. 
(Programs can be loaded down-line if necessary, for example when the 
diagnostic load medium of the system under test is malfunctioning.) 



2.3 The VAX Diagnostic Supervisor 



The previous chapter detailed the various uses and users of a diagnostic 
program. The above section describes the run-time environments 
supported for VAX diagnostic programs. If a diagnostic program designer 
had to include proper interfaces for all users and environments in each 
program he or she developed, the task would become burdensome. For 
this reason the VAX Diagnostic Supervisor (VDS) was developed for 
diagnostic macroprograms designed to run on VAX systems. The VAX 
Diagnostic Supervisor is a control program that will load, execute, and 
provide run-time services to diagnostic programs. 

The VDS is divided into two major sections. One section is an interface 
between the VDS and the program user and is called the "human 
interface." The other is an interface between the VDS and the diagnostic 
program and is referred to as the "program interface." 

The human interface consists of a command line interpreter (CLI) 
that receives and processes commands typed on a terminal by a user. 
Commands supported by the CLI include those for loading and running 
diagnostic programs, selecting which device units to test, displaying 
execution summaries, and controlling program looping. 

The program interface consists of a set of service routines for service calls 
from the diagnostic program to the VDS, along with a mechanism for 
dispatching calls from the program to the proper routines in the VDS. 
These service routines provide the diagnostic program with convenient 
methods for performing device I/O, formatting error messages, controlling 
program loops, storing and retrieving system-specific device parameters, 
prompting the user for additional run-time parameters, and providing file 
management facilities. 
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The specific purposes of the VDS are: 

• Provide a common human interface for all diagnostic programs. 
With the large number of VAX diagnostic programs in existence, it 
is important that users not be required to spend time learning how 
to use each one. The VDS provides the user with a standard set of 
commands and functions that can be performed for all diagnostic 
programs. 

• Insulate the diagnostic program from the run-time environment. The 
VDS performs any communication that may be needed between the 
diagnostic program and the run-time environment, whether it is VMS 
(user mode), APT, APT/RD, or standalone. 

• Insulate the diagnostic program from processor-specific hardware 
differences. The VDS performs I/O initialization operations that are 
unique to the type of VAX processor being used. Thus, the diagnostic 
program does not need to be concerned with knowing the type of VAX 
processor. 

• Make the programmer's job easier. Providing facilities for formatting 
error messages, controlling program looping, initiating I/O activity, 
manipulating files, and other services not only guarantees consistency 
among diagnostic programs from the user's standpoint, but also greatly 
reduces the development effort necessary to produce a new program. 

The VDS is used by most, but not all, diagnostic macroprograms written 
for VAX systems, as will be shown in the following section. 

Later chapters of this manual discuss the VDS in detail. The VDS is 
introduced at this point in the manual because it plays a role in the VAX 
diagnostic strategy. 



2.4 Introduction to the VAX Diagnostic Strategy 



In order to ensure a careful, comprehensive, step-by-step approach to 
diagnosing problems, a strategy for diagnosing VAX systems has been 
developed. This strategy, generally referred to as the "VAX diagnostic 
strategy," has been to create a hierarchy of diagnostic programs based 
on hardcore requirements. Programs higher in the hierarchy require 
greater hardcore (they require a larger portion of the whole system to 
be operating). These programs provide a versatile human interface and 
are less likely to require exclusive use of the system under test. These 
diagnostics will detect the existence of faults and help identify the region 
which contains the faulty module or FRU. Conversely, programs lower in 
the hierarchy will test specific devices more intensely and therefore can 
identify faults. When diagnosing a customer's system, it is recommended 
to begin by using diagnostic programs which require a large hardcore 
(high level), then by using lower level diagnostics as the region at fault is 
identified more specifically. 
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The diagnostic strategy has been implemented by creating various types, or 
"levels," of diagnostic programs. These levels are based on the following: 

• The VAX hardware can be divided into various building blocks. These 
building blocks create a whole system when connected together, and 
consist of: 

— A system console 

— A CPU "cluster" consisting of processor, memory, and I/O 
chaimels 

— Peripheral devices 

• Fault diagnosis can occur while the system's operating system is 
nmning. 

• The VAX Diagnostic Supervisor can be used when appropriate. 

By using these considerations, a set of five program levels has been 
defined. The diagnostic programs belonging to each level possess 
characteristics which differentiate them from programs belonging to 
the other levels. These characteristics are related to the program's run- 
time environment, hardware environment (see below), and method of 
performing I/O operations (see below). 

Table 2-1 introduces each program level by listing its level name and the 
run-time environment associated with it. 

Table 2-1 Program Levels and Run-Time Environments 
Level Run-Time Environment 

1 Runs under an operating system. 
2R Runs under VDS in user mode only. 

2 Runs under VDS in both user and standalone modes. 
(There are no new programs which use QIOs for this level.) 

3 Runs under VDS in standalone mode only. 

4 Runs in standalone witliout VDS. 

5 Runs in WCS or system console, not in VAX main memory. 

A program's hardware environment is the minimum hardware 
configuration on which the program will execute. (Do not confuse this 
with the program's hardcore, which is the minimum amount of hardware 
that must be functioning properly in order for the diagnostic program to 
execute. For example, the hardware environment of a program to test a 
disk controller would be the CPU cluster, buses connecting the controller 
to the cluster, and the controller itself, while the hardcore requirements in 
this case would be the CPU cluster and the buses.) 

Three different hardware environments can be defined for VAX diagnostic 
programs. The hardware environments relate to the building blocks listed 
above. These environments are: 

1 Console environment. Consists of only the system console and the 
console load device. 
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2 CPU cluster environment. Consists of the system console, the VAX 
processor, main memory, and I/O channels. 

3 System environment. Consists of the system console, the CPU cluster, 
and all attached peripherals. In other words, this is the whole system. 

Figure 2-1 illustrates the hardware environments for a typical VAX 
hardware configuration. 

Figure 2-1 Hardware Environments for VAX Diagnostic Programs 
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The hardcore requirements and the hardware environments of the levels 
vary, with both increasing as the hierarchical level increases. Thus, level 
1 programs have the greatest hardcore requirements and largest hardware 
environments, while level 5 programs have the least and smallest. 

The hardware environment and hardcore requirements of each program 
level are listed in Table 2-2. 



Table 2-2 IHardware Environments and Hardcore Requirements 



Level Hardware Environment 



Hardcore Requirements 



1 System 

2R Enough of system for VMS to 

execute, plus UUT 

2 Same as 2R in user mode 
Same as 3 in standalone mode 

3 CPU cluster, UUT, load device 

4 CPU cluster 

5 Console, CPU cluster 



Enough of system for the operating 
system to execute 

Enough of system for VMS to 
execute 

Same as 2R in user mode 
Same as 3 in standalone mode 

CPU cluster, load device 

Console, subset of CPU cluster 

Subset of console 
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2.5 Methods of Performing I/O 



Perhaps the most significant difference among the various program levels 
is the method of performing I/O operations. The various I/O methods 
are determined by the run-time environments existing for VAX diagnostic 
programs, since run-time environments generally put restrictions on I/O 
operations. 

Before discussing the methods of performing I/O operations used by 
each level, it is necessary to define three t3?pes of I/O operations that are 
provided by the run-time environments, as follows: 

• Physical I/O. In physical I/O operations, references can be made to 
the actual physically addressable units of the device or its storage 
medium, such as sectors on a disk, ignoring any block structuring or 
file-structuring algorithms that may have been created for the device by 
software. 

• Logical I/O. For logical I/O operations, a disk-tj^e storage device 
may be referenced by addressing "logical" blocks on the device 
(blocks defined by software, such as the 512-byte blocks defined by 
VMS). Blocks are referenced relative to the beginning of the storage 
medium, and are numbered from to n, where n is the last block. 
File-structuring algorithms are ignored. 

• Virtual I/O. With virtual I/O operations, software-defined blocks are 
referenced relative to the beginning of a file. They are numbered from 
1 to n, where n is the last block in the file being referenced. This 
method of I/O takes full advantage of software-defined blocking and 
file-structuring on the storage medium. 

A more detailed discussion of the I/O types can be found in the VAX/VMS 
I/O User's Guide, which should be read before the development of a level 1 
or 2R program is initiated. 

In level 1 programs, I/O transfers are accomplished by issuing requests to 
the operating system, such as the $QIO system service call or by using the 
Record Management Services (RMS) routines of VMS. Level 1 programs 
are expected to perform virtual, or sometimes logical, I/O operations, 
allowing them to execute without corrupting existing data on any storage 
media and thus not affecting the operation of any other processes executing 
concurrently. 

For level 2R programs, I/O transfers are performed by issuing the $QIO 
service call, but in this case the VAX diagnostic supervisor fields the 'call. 
The VDS in turn passes the I/O request to VMS, where the I/O operation is 
actually performed. Level 2R programs are used for exercisers of devices 
or entire systems and for functional testing of devices when one does not 
want to force other users off the system. 
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Physical I/O transfers are generally used in level 2R programs, since this 
t5?pe of transfer allows access to all areas of the device medium and thus 
provides maximum usage of the device's logic. Physical I/O transfers 
provide minimum device access time. Use of physical I/O implies that 
a "scratch" medium will have to be placed in the UUT in order to not 
corrupt valid user data, unless the device possesses special "maintenance 
cylinders" reserved for use by diagnostic programs. It also requires that 
the user of the program be granted special VMS "user privileges" (see 
the VAX/VMS Command Language User's Guide). While physical I/O is most 
often used, logical or even virtual I/O may be more appropriate in some 
cases. Level 2 programs may also perform I/O transfers using the $QIO 
service call, with the VDS fielding the call. In user mode, the VDS passes 
the request on to VMS. In standalone mode, the VDS itself services the 
request. It is not clear that one diagnostic program should be written 
to run in two different run-time environments, since the program is at 
best a compromise of the sometimes conflicting characteristics of the two 
environments (for example, ability to run with other users in user mode 
versus the ability to have unlimited system access in standalone mode). 
Also, the difficulty in maintaining this duplicity of functionality within the 
VDS is considerable. Therefore, LEVEL 2 DIAGNOSTIC PROGRAMS 
WHICH USE QIOs ARE NO LONGER BEING DEVELOPED AND WILL 
NOT BE ACCEPTED FOR RELEASE. 

Level 3 diagnostic programs perform their I/O operations directly. That 
is, they address the device's registers and field its interrupts. The VDS 
provides services for creating a "channel," or addressing path, to the 
device. This insulates the diagnostic program from the specific VAX 
processor tj^e, enabling the programmer to create code that does not 
need to be concerned with I/O characteristics of particular processors. 
Since at this program level there are no software provisions for block 
formatting or file struchxring, the only I/O type possible is physical. Logic 
tests (see Chapter 1) are written in level 3, since this level allows relatively 
comprehensive access to the device under test while also providing the 
VDS's common user and programming interfaces. Level 4 programs 
are not used to test peripheral I/O devices and thus do not perform I/O 
operations. They should only be used to test those portions of the CPU 
cluster environment that are considered to be a part of the VAX Diagnostic 
Supervisor's hardcore. 

Level 5 programs generally do not perform I/O operations, since they are 
generally microprograms used to test portions of the processor. However, 
some level 5 programs (specifically those diagnostic microprograms that 
test peripheral devices) may perform physical I/O operations. 

Table 2-3 summarizes the I/O methods used in the various program levels 
and also indicates the types of diagnostic programs generally assigned to 
each level. 
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Table 2-3 I/O Methods and Program Types 



Level I/O Method Types of Programs 

1 Virtual or logical, using operating System exercisers 
system I/O services 

2R Generally physical (but virtual or Exercisers and function tests of 

logical are allowed), using VMS peripheral devices 
QIO sewice 

2 Physical, using VMS/VDS QIO Function tests of peripheral devices 
sewice 

3 Physical, using program-defined Function tests and logic tests of 
I/O functions peripheral devices 

4 None Function and logic tests of CPU 

cluster 

5 None, or physical using program- Microprograms 
defined functions 



2.6 Applying the VAX Diagnostic Strategy 



Applying the VAX diagnostic strategy to a specific product usually implies 
developing a set of diagnostic programs to test the product. 



2.6.1 Testing the CPU Cluster 



The VAX CPU cluster is tested by a set of programs, existing at several 
program levels, as follows: 

• Level 5 

— Console tests 

— Processor tests 

— Memory tests 

• Level 4 

— VAX instruction set test (hardcore for VDS) 

— Cache and translation buffer tests (VAX-11/750 only) 

• Level 3 

— Memory tests (if no level 5 test possible) 

— Channel adapter tests 

— Cluster exerciser 

This set of programs implements the VAX diagnostic strategy by providing 
a set of building blocks by which a system may be tested, starting with the 
level 5 basic processor tests and ending with the level 3 cluster exerciser, 
which is a program meant to exercise all components of the cluster. 



2-8 



VAX Diagnostic Programs 



Level 5 programs may not exist for all VAX processors, since they are 
microprograms. Ideally (but not necessarily), microdiagnostic programs 
should be executed in a separate console processor (front end), making 
use of a writable control store (WCS). Low-cost VAX processors may not 
provide these features. 

Most of the programs can be used on all types of VAX processors. 
Therefore, when a new processor is developed, it is not necessary to 
produce a whole new set of programs for testing the new cluster. However, 
a new processor-specific module must be added to the cluster exerciser. 



2.6.2 Testing Peripheral Devices 



Thorough testing of a peripheral device requires the development of three 
different diagnostic programs. For each device t)rpe the following will 
t5^ically (but not necessarily) exist: 

• A level 3 logic test 

• A level 3 function test 

• A level 2R function test 

This group of programs implements the diagnostic strategy by providing 
a facility for producing very accurate and detailed identifications of fault 
conditions via the level 3 programs and by also providing a method by 
which the device may be tested without bringing down the customer's 
operating system via the level 2R program. 

The level 3 logic test will provide the greatest detail of error resolution, 
indicating which section of logic is fedling. This program will be used by 
technicicuis to repair bad logic boards, and will provide very high test 
coverage. Some devices contain ROM-resident microprograms ("self- 
tests") that perform logic testing, making a level 3 logic test unnecessary. 

The level 3 function test will provide a comprehensive test of all of the 
device's functions. This program will be used to determine accurately 
whether or not a device is operating correctly. This is the definitive 
function test and provides very high test coverage. Level 3 function tests 
are usually required even if the device possesses self-testing capabilities, 
because self-tests generally are not capable of complete detection of 
function failures. The level 2R program will typically consist of a subset of 
the level 3 function test. It will test as much of the device's functionality 
as can be tested in the user (VMS) environment. The tests it contains are 
exact or approximate copies of tests existing in the level 3 program. 

A typical sequence of use for these programs, when dealing with a system 
at a customer site, is as follows: 

1 The customer (or field service) suspects a fault existing in the device. 

2 The level 2R program is run to see if the error can be detected without 
stopping the operating system. If the error is found, go to step 4. 
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3 If the level 2R program cannot identify the fault, the operating system 
is brought down and the level 3 function test is run. 

4 The fault is identified emd the failing FRU is replaced. The operating 
system is then brought back up. 

5 The failing FRU is brought back to DIGITAL, where the level 3 logic 
test, the level 3 function test, or perhaps a module test station is used 
to identify the failing logic on the FRU. The FRU is repaired. 

2.7 Guidelines for Writing VAX Diagnostic Programs 

This section contains general guidelines that should be followed when 
writing VAX diagnostic programs. 



2.7.1 Level 1 Guidelines 



Level 1 diagnostic programs are usually used as exercisers of the entire 
hardware system. Level 1 is used when it is necessary to cause various 
concurrent activities to take place, using numerous types of devices and 
other hardware and software resources provided by the system. 

Since no standard human interface exists for level 1 programs, it is 
important for the program developer to design a convenient "user- 
friendly" interface, using such techniques as English-like commands, 
menus, and detailed "help" messages. 

Error reporting will also be the responsibilify of the program designer. 
However, much use can be made of the system software's error reporting 
facilities. 



2.7.2 Level 2R Guidelines 



Level 2R programs run under the VDS in user mode. These programs test 
device functionalify and must test as many of a device's functions as can 
be performed under the constraints of the operating system. 

I/O is performed by issuing QIO requests to the VDS. These requests 
are passed directly to VMS, which performs the indicated operations and 
returns an error status. Actual I/O activity is controlled by VMS device 
drivers. Full use should be made of the returned error information, which 
may include device register contents. All available information should be 
displayed to the user via the VDS error reporting facilities. 

The level 2R program should be written after the level 3 function test has 
been developed, since the level 2R program should be a subset of the level 
3 program. Take the level 3 program, change the I/O method from the 
channel services of the level 3 (see below) to QIO calls, and remove any 
functions that the VMS operating system will not allow to be performed. 
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2.7.3 Level 2 Guidelines 

DO NOT WRITE ANY NEW LEVEL 2 DIAGNOSTIC PROGRAMS WHICH 
USE QIOs. 



2.7.4 Level 3 Function Tests Guidelines 



Level 3 programs run under the VDS. There is no operating system 
software to limit the functionality or access rights of the diagnostic program. 
However, the program should use VDS channel services (discussed in the 
following chapters) for creating data paths to the device under test, in 
order to eliminate the need for diagnostic programs to be concerned with 
processor-specific details of bus adapter mapping. 

I/O operations are initiated and interrupts are fielded by the diagnostic 
program. Since these programs have unlimited access to system hardware 
resources, detailed error messages can and should be created that contain 
dumps of pertinent registers. 

Level 3 function tests should test every function that the device is capable 
of performing. Illegal orders and combinations should also be tried. 

Not only should the data transfer functions be performed, but 
electromechanical functions should also be tested to ensure that they 
operate within specified parameters and time intervals, as should the 
operator-related functions, such as setting the write-protect switch. All 
timing operations must be performed by using the timing services provided 
by the VDS, since the VDS takes into account the type of VAX processor 
being used and corrects for timing differences between processor t5Tjes. 



2.7.5 Level 3 Logic Test Guidelines 



Because logic tests are designed to help technicians repair malfunctioning 
logic boards, it is important that they provide good fragmentation of activity 
in the logic, causing as little overall activity as possible at a given point in 
execution time. Every effort should be made to concentrate electrical 
activity to one small section at a time. The extent to which this is possible 
depends on the particular hardware design, and it is often more of an ideal 
than an attainable goal. 

The first section of logic to be tested should be that which is most likely to 
be depended on by other logic. Thus, a general sequence of steps this type 
of program might contain would be as follows: 

1 Test the interface between the device's controller and the I/O bus to 
which it is attached, including address decoding logic and logic used in 
referencing controller registers. 

2 Test the controller's commands and the logic associated with each 
command, using the device's "maintenance mode" if applicable. 

3 Test the data transfer functions of the device, again using maintenance 
mode. 
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In each step, invalid and borderline conditions should be checked. For 
example, purposely formatting data improperly, issuing illegal function 
codes, and making illegal references to device registers are techniques that 
can be used. 

All timing operations must be performed by using the timing services 
provided by the VDS, since the VDS takes into account the type of VAX 
processor being used and corrects for timing differences between processor 
t5^es. 



2.7.6 Level 4 Guidelines 



Level 4 programs are used only to test those parts of the system that 
belong to the VDS environment's hardcore and that are not tested by level 
5 programs. For example, level 4 programs are needed to test the VAX 
instruction set, the translation buffer, and cache of some (but not all) VAX 
processors. 

If a new level 4 program needs to be developed, the following rules should 
be adhered to: 

• Use straight-line code (no subroutines). This makes it easier for the 
user to step through the program when necessary. 

• Use a minimum mstruction set, at least at the beginning of the 
program. 

• Write the program in position-independent code, so that it may be 
loaded and executed in any section of memory in case there is a bad 
area of memory. 

• Create a section of code to handle unexpected interrupt conditions, 
such as machine checks or other traps. 

• Do not use any terminal I/O routines unless all the logic required to 
perform the I/O has been previously tested. 

• When an error is detected, execute the HALT instruction. 

• Use the general purpose registers (GPRs) to pass information to the 
user. For example, on a data comparison error, the expected and actual 
bit patterns can be placed in the GPRs. 

• Store the current test and subtest numbers in some location, such as 
address 0, so the user can obtain them. 

• Provide very precise program documentation. Since no terminal 
displays can be provided, the user must be able to use the PC of 
a failure to find out exactly what type or error occurred and what 
was happening to cause the error. This information must be clearly 
indicated in the program listing. 
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2.7.7 Level 5 Guidelines 

Level 5 programs are microprograms. Smce the microcode and hardware 
design of each VAX processor tj^e is different, there must be a separate 
set of level 5 programs for each processor t3^e. Following are general rules 
that should be followed when developing diagnostic microprograms: 

• Diagnostic microprograms should always be designed to perform 
bottom-up testing. 

• Program loops should be as short as possible, in order to isolate 
electrical activity to as small an area of the logic as possible. Ideally, 
these loops should enable a technician to isolate a fault to the failing 
component. 

• Error reports should be precise enough for the technician to locate the 
code in a program listing. The listing should contain a clear description 
of what logic was being tested and which component may be failing. 
Avoid referring to components by their "E-numbers," since these can 
be changed when ECOs are issued. 

• A level 5 program should be able to test every component except those 
requiring an external stimulus. 
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3.1 Introduction 



This chapter describes the structure of a diagnostic program designed to 
run under the VAX Diagnostic Supervisor (VDS). This group of diagnostic 
programs is referred to as the VAX/DS diagnostic programs. 



3.1 .1 Overview of tlie VAX Diagnostic Supervisor 

The VDS is divided into three major segments, each segment performing 
a separate function. These segments are the command line interpreter, the 
dispatcher, and the VDS macros and system services. 

• Command Line Interpreter 

The command line interpreter provides the human interface to the 
diagnostic program. It allows the diagnostic program user to select 
which programs to execute, which portions of that program to run, and 
which of the system's device units to test. 

The command line interpreter implements the commands described in 
the VAX/DS Diagnostic Supervisor User's Guide. 

• Dispatcher 

The dispatcher controls the operation of the diagnostic program. It 
is given control whenever the command line interpreter recognizes 
a START or RUN command. The dispatcher will call the various 
elements of the diagnostic program (such as the program's initialization 
code, tests, cleanup code, and summary routine, aU. of which are 
discussed in this chapter) at the appropriate times. 

• VDS Macros and System Services 

All linkages between the diagnostic program and the VDS are specified 
by a set of macros. Some of these macros facilitate program shucture, 
program control mechanisms and symbol definitions; others provide 
system service routines to perform functons such as error reporting, 
I/O operations, and event synchronization. The system services will be 
discussed in Chapter 5. 

The program structure macros are used to define the various sections, 
tables, and data structures making up the diagnostic program. For 
example, every source module making up the diagnostic program 
must be delimited by the $DS_BGNMOD and $DS_ENDMOD 
macros; every test must be delimited by the $DS_BGNTEST and 
$DS_ENDTEST macros. Using the program structure macros enables 
the VDS dispatcher to locate and call the initialization code, tests, and 
cleanup code. Most of the program structure macros are required in 
every diagnostic program. 
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The program control macros are used to affect the program's execution 
path and provide such facihties as looping and branch-on-error. For 
example, the $DS_CKLOOP macro can be used to define the upper 
bound of a program loop. 

The S}mibol definition macros define global S3mibols used by the 
other macros, the VDS, and the diagnostic program. For example, 
the $DS_HDRDEF macro defines symbols for the locations within the 
diagnostic program's header (See Section 3.3.1). 

Figure 3-1 illustrates the VDS segments and their relationship to a 
diagnostic program. 

Figure 3-1 VDS Overview 
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3.1 .2 Overview of a VDS Diagnostic Program 

Every diagnostic program must possess several major elements: 

• Initialization Code 

This is code that is executed before a device unit is tested. It performs 
the operations necessary for creating a data link to the unit, and 
prepares the unit for testing. 

• Tables 

There are various tables residing in the diagnostic program for the 
purpose of enabling the VDS to control the diagnostic program's 
operation. 

• Tests 

These are the achial device tests. Tests will detect errors and represent 
an entity on which to loop. 
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• Error Reporting Routines 

This code will report detected error conditions and any other pertinent 
information related to the error. 

• Cleanup Code 

This code performs any operations that might be needed to leave the 
UUT in a stat? such that it is available to the next system user. 

Additionally, a diagnostic program can possess other optional elements: 

• I/O routines 

• Interrupt service routines 

• Multiprocessing routines 

Note that the diagnostic program contains no dispatching mechanism. The 
program should be viewed simply as a set of low-level routines to be called 
by the VDS when needed. 

Illustrations of program flow for both serial testing and parallel testing of 
devices follow. The program flow is accomplished through interaction 
between the diagnostic program and the VDS. 

Example 3-1 Program Flow 

Progreim Flow for Serial Testings 

Get RUN or START command. 
Get passes_requested. 
Passes_executed =0. 
REPEAT 

Unit_number = 0. 
REPEAT 

Call initialization code. 
Call selected tests. 
Call suiranary code. 
Unit_number = unit_number + 1. 
UNTIL unlt_nuinber = max_unit_nuinber . 
Passes_executed = passes_executed + 1 . 
UNTIL passes_executed EQL passes_requested. 
Call cleanup code. 

Program Flow for Parallel Testing; 

Get RUN or START command. 
Get passes_requested. 
Pas ses_ executed = 0. 
REPEAT 

Unit_nuiiiber = 0. 

REPEAT 

Call initialization code. 
Unit_number = unit_number + 1. 

UNTIL unit_nuinber = max_unit_number. 

Call selected tests. 

Call summary code. 

Passes_executed = passes_executed + 1. 
UNTIL passes_executed EQL passes_requested. 
Call cleanup code. 
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3.1.3 Memory Layout 



Figure 3-2 shows the layout within memory of the various pieces of 
software existing when a VDS diagnostic program is executing. All 
addresses are virtual. In standalone mode, the virtual addresses are the 
same as the physical addresses, so the illustration represents a true picture 
of the actual program layout in memory. In user mode, VMS' memory 
management is in operation and therefore the virtual addresses shown 
have no relation to the physical addresses. 

The base address of a diagnostic program is 200 (hex). (When a diagnostic 
program is linked, a base address of 200 (hex) must be explicitly specified.) 
The loadable image of a diagnostic program may not extend beyond virtual 
address F9FF (hex). Thus, the maximum size for the loadable image of a 
diagnostic program is 63487 (decimal) b)rtes. 

Addresses from FAOG to FFFF are used by the VDS to communicate with 
Automated Product Test (APT). The VDS loadable image starts at virtual 
address 10000 (hex). At run-time, the VDS occupies a contiguous portion 
of memory starting at 10000 (hex). The total size of this area depends on 
such parameters as the t3rpe of processor being used, the size of memory, 
and the number of attached devices. 

Two areas of memory are used to allocate buffer space to diagnostic 
programs. The first area is any space that may exist between the top of the 
diagnostic program's loadable image and address FAOO (hex). The second 
(and generally larger) area consists of addresses above the highest address 
used by the VDS. Allocation of this buffer space to a diagnostic program is 
discussed in Section 4.3.3, Memory Allocation. 

Figure 3-2 VDS Memory Layout 
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3.2 P-Tables 



3.2.1 Introduction to P-Tables 

In order to test a device, a diagnostic program must have access to the 
device's characteristics. Since some device characteristics are system- 
specific, it is impossible to define them permanently in the diagnostic 
program. Instead, it is necessary to provide a means by which these 
system-specific characteristics can be specified at run-time. The VDS 
provides the hardware parameter tables, or simply p-tables, for this 
purpose. 

A p-table is a data structure that contains device information that is 
necessary for a diagnostic program to access the device. P-tables are 
constructed by the VDS: 

• for a specific device, when the program user tjrpes the ATTACH 
command (refer to the VAX/DS Diagnostic Supervisor User's Guide). 

• for devices that are part of the boot path (constructed at boot time). 

• for all supported devices when the autosizer is run. 

Once the VDS has created the p-tables, the diagnostic program can 
reference the tables to obtain information necessary for testing a UUT. 

When the user attaches a device, one of the parameters which must be 
specified is the device's link. The link is the piece of hardware to which 
the device is connected. The link must have been previously specified 
with another ATTACH command so that its p-table already exists. A set of 
ATTACH commands will result in a tree structure of device links. The root 
of this tree is a pseudo-device called HUB. This pseudo-device was created 
because the actual hardware interconnect depends on the type of processor 
being used, for example, the XMI on the VAX 6200. In general, processors 
and buses are linked to HUB, adapters are linked to buses, controllers are 
linked to adapters, and device units are linked to controllers. Figure 3-3 
illustrates the manner in which p-tables describe a hardware system. 
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Figure 3-3 Sample Hardware Configuration and Associated P-Tables 
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The p-table for a particular device wiU contain the information provided by 
the ATTACH command arguments. Each p-table will contain the following 
standard information: 

• Device type - This is the product name for the device, such as KA62A 
or DWMBA. 

• Device's generic name - This is the name that the device will be 
referred to, such as KAO or DWMBA2. When possible, the device 
name will conform to VMS naming conventions. 

• Address of p-table for device's link 
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Device characteristics — The information which must be included in a 
p-table to sufficiently describe a device. This depends on the type of 
device and its link. For example, a device linked to a UNIBUS requires 
the UNIBUS CSR address and bus request level, plus the device's 
interrupt vector address. 



3.2.2 P-Table Format 



All p-tables have a standard format. Each p-table is divided into three 
sections. The first section contains device-independent fields. All p-tables 
for all devices contain these fields. Each device-independent field in the 
p-table has a mnemoruc assigned to it which can be used by the diagnostic 
program when these fields are referenced. The second section of the 
p-table contains device-dependent information. This section is unique to 
the t3^e of device being described. The third section contains an extension 
to the device-independent fields. (In the following discussion, references 
to the device-independent section of the p-table include this extension). 
Figure 3-4 shows the standard layout of all p-tables. 
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Figure 3-4 P-Table Layout 
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Below are the descriptions of the device-independent p-table fields. The 
fields prefaced with HP$ are defined by $DS_HPODEF and are offsets 
from the base of the p-table. The fields prefaced with HPE$ are the fields 
in the extension of the device-independent p-table. They are defined by 
$DS_HPEODEF and are offsets fi:om the base of the extended p-table block 
(EPB). 



3-8 



Core Components of a VAX/DS Diagnostic Program 



HP$Q_DEVICE — A VMS-type quadword descriptor of the device name 
string ^see HP$T_DEVICE below). The first word of the field contains the 
length of the device name string, and the next word is unused. The second 
longword contains the address of the device name string. If the device 
name conforms to the short format, that is, ggan, the second longword 
contains the address of HP$T_DEVICE. If the device name conforms to the 
long format, that is, name$ggan or $alloclas$ggan, the second longword 
contains the address of HPE$T_DEVICE. The field HPE$T_DEVICE is 
used simply because names with the long format will not fit in the field 
HP$T_DEVICE. 

HP$W_SIZE — The size of the entire p-table in bytes. This mcludes both 
the device-independent and the device-dependent p-table fields. 

HP$B_FLAGS — Flags used by the VDS when the device is uiitialized. 
Flags are defined as follows: 

• HP$M_ ALLOC — (bit 0) - If set, indicates that the VDS must request 
VMS to allocate ($ALLOCATE system service) the device before it can 
be tested in user mode. 

• HP$M_WASALL — (bit 1) — Set by VDS if a device has been 
successfully allocated. 

• HP$M_NAME — (bit 2) - Set by VDS if the device name uses the long 
format. 

• (Bits 3-7) — Unused. 

HP$B_DR1VE — The unit number of the device. This is the number 
appearing at the end of the device's generic name, such as 7 in _TTA7. 
If the unit number is greater than 255, it can be accessed in the extended 
p-table field, HPE$W_EXT_DRIVE. 

HP$T_DEVICE — An ASCII string representing the device's generic name. 
The device name is stored here only if it conforms to the short format, that 
is, ggan. 

HP$A_DEVICE — The virtual address of the lowest-addressed device 
register. The type of register being pointed to depends on the device type. 
For example, it would be a CSR for a UNIBUS device and a configuration 
register for an SBI device. 

The virtual address must be assigned to PI space (bit 30 set). This is 
because the VDS maps all physical I/O addresses through virhial PI space 
when memory management is enabled (standalone mode). 

HP$A_DVA — This is the base of the virtual address space assigned to 
this device. Devices linked to this device will have address assignments 
relative to this base address. When the VDS constructs a new p-table for 
a device linked to this one, it copies this field into the liriked device's 
HP$A_DEVICE field. When the device address for the new device is 
fetched from the user, it can be added to the base address already in 
HP$A_DEVICE. 

The virtual address must be assigned to PI space (bit 30 set). This is 
because the VDS maps all physical I/O addresses through virhial PI space 
when memory management is enabled (standalone mode). 

3-9 



Core Components of a VAX/DS Diagnostic Program 



The HP$A_DVA field is not always relevant. An example of its use is the 
case of UNIBUS adapters. Each UNIBUS is assigned to a certain base 
address. The addresses of devices connected to a particular UNIBUS 
are added to the UNIBUS's base address to obtain the device's actual 
physical address. A UNIBUS's base address is stored in the HP$A_DVA 
field for a UNIBUS's p-table. When a controller is linked to the UNIBUS, 
its HP$A_ DEVICE field will be initialized to the value contained in the 
UNIBUS's HP$A_DVA field. Subsequently, the user will be prompted 
for the conhroUer's 18-bit address. This address can be stored in the low- 
order 18 bits of HP$A_DEVICE to result in a full physical address for the 
controller. 

HP$A_LINK — The address of the p-table for the device to which this one 
is linked. If this device is linked to HUB, the field contains 0. 

HP$W_ VECTOR — If relevant, contains the vector address through which 
the device will interrupt. This address is an offset into the System Control 
Block (SCB). 

HP$T_TYPE — Contains a counted ASCII string representing the device 
type, such as KA62A, KDB50, or RA90. 

HP$A_DEPENDENT - The first location of the device-dependent section 
of the p-table. 

HPE$T_DEVICE — An ASCII string representing a device name if it is in 
the long format, that is, name$ggan or $alloclas$name. 

HPE$W_EXT_DRIVE — The unit number of the device which is the number 
appearing at the end of a device's name, such as 293 in TT293. This field 
will allow the attachment of drive numbers greater than 255. 

HPE$A_EPB - Address of the extended p-table block. This address is 
always 4 bytes less than the end of the entire p-table. It can be used to 
reference the extended part of the device-independent ptable. Refer to 
Example 3-7. 

The HP$W_SIZE, HP$Q_DEVICE, HP$B_DRIVE, HP$T_DEVICE, 
HP$A_LINK, HP$T_TYPE, HPE$W_EXT_DRIVE, and HPE$T_DEVICE 
fields are filled in automatically by the VDS (when relevant). The other 
fields are loaded (if needed — not all fields are relevant to all devices) in 
accordance to directions contained in the p-table descriptors (see below). 

The fields within the device-dependent section also have mnemonics, but 
they are unique to the device. 



3.2.3 P-Table Descriptors 



3.2.3.1 Introduction to P-Table Descriptors 

The VDS builds a p-table by referring to a p-table descriptor. This is a set 
of instructions that indicates the size and format of the device-dependent 
p-table fields. When the VDS builds a p-table, it refers to the p-table 
descriptor of the specified device type in order to determine how to 
construct the device-dependent fields. 
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Instructions within tiie p-table descriptor specify the following types of 
information to the VDS: 

• The device t5rpe 

• A prompting message for each device-dependent hardware parameter 
to be stored in the p-table 

• The format in which user response to the device-dependent prompts is 
to be interpreted 

• The p-table field in which the responses to the device-dependent 
prompts are to be stored 



3.2.3.2 Creating P-Table Descriptors 

There are two steps when you create a p-table descriptor: 

1 Define the representation of the memory space required for the 

p-table's device-dependent fields, that is, a field declaration including 
name and size of each field. When the VDS builds a p-table, skeletons 
of both the device-independent and device-dependent fields are copied 
into a djmamic memory storage area, and the fields are filled in with 
the proper information. 

Example 3-2 presents the KDB50 controller p-table field declaration 
in MACRO-32 and BLISS-32. This step must be completed before the 
descriptor can be written. 

Example 3-2 Device-Dependent Field Declaration for the KDB50 
Controller 



MACRO-32 ; 

.MACRO $DS_KDB50_DEF $GBL 

$DEFINI KDB50 , $GBL , HP$A_DEPENDENT 

$DEF HP$L_KDB50_IP 

$DEF KDB50$L_IP, .BLKL, 1 

$DEF HP$B_KDi50_BR 

$DEF KDB50$B_Br7.BLKB,1 

$DEF HP$B_KDB50_NODE_ID 

$DEF KDB50$B_NODE_Id7 • BLKB, 1 

$DEF HP$B_KDB50_BURST 

$DEF KDB50$B_BURST, . BLKB, 1 

$DEF HP$K_KDB50_LEN 

$DEF KDB50$K_LEN 

$DEFEND KDB5 , $GBL , DEF 

.ENDM $DS_KDB50_DEF 

BLISS-32! 

$DS_KDB50_DEF= 

SET 

KDB50$L IP= [HP$K_LENGTH+0,0,32,0], 

HP$L KDi50_IP= (HP$K_LENGTH+0,0,32,0], 

KDB50$B BR= [ HP$K_LENGTH+4 ,0,8,0], 

HPSB KDi50_BR= [HP$K_LENGTH+4, 0, 8,0 ] , 

KDB50$B_NODE_ID=[ HP$K_LENGTH+5 ,0,8,0), 

HP$B_KDi50_N0DE_ID=[ HP$K_LENGTH+5 ,0,8,0], 

KDB50$B BURST= [ HP$K_LENGTH+6 , , 8 , ] , 

HP$B_KDB50_BURST= [ HP$K_LENGTH+6 ,0,8,0] 

TES, 
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The device-dependent fields, defined by the field declaration are: 

• HP$L_KDB50_IP, longword storage for the address of the UNIBUS 
CSR 

• HP$B_KDB50_BR, byte storage for bus request level 

• HP$B_KDB50_NODE_ID, byte storage for node id 

• HP$B_KDB50_BURST, byte storage for the burst data transfer rate 

Use the p-table descriptor macros to define the instructions which 
will supply the device-dependent information to the p-table. Also, 
you must develop instructions for filling in the following device- 
independent fields, if they are relevant to the device: HP$A_DEVICE 
HP$A_DVA, HP$B_FLAGS, and HP$W_VECTOR. 

The p-table descriptor macros make use of a temporary storage location 
referred to as the value register. Certain macros cause information to 
be read from the ATTACH command line and placed into the value 
register; other macros can manipulate the value register's contents, and 
others can transfer those contents into fields of the p-table. 

The following general guidelines should be followed when you create a 
p-table descriptor: 

• Each user prompting message should provide a clear indication of 
what information the user must provide. 

• Responses should be requested in a format that is relevant to the 
particular type of data being requested. For example, UNIBUS 
addresses should be formatted in octal instead of hexadecimal, 
since that is their normal format. 

• Only information which is necessary to reference a device should 
be included. This information may include such items as the 
device's address, interrupt vector, and bus request level (BR). Do 
not include information which will only be used by one diagnostic 
program; remember that a p-table for a particular device will be 
used by all diagnostic programs which test that device. Information 
needed by a particular program or test should be obtained via the 
$DS_ASKxxxx macros (see Chapter 5). 

The p-table descriptor macros are briefly described below. For more 
information, see Chapter 5. 

• $DS_$INITIALIZE - This is the first macro in any p-table 
descriptor. It indicates the device type, the p-table size, the 
maximum number of units allowed, and the name of the device 
driver used for level 2 diagnostic programs (see Chapter 2). 

• $DS_$NAME — Specifies a format to which the device unit's 
generic name must conform. When possible, this format will 
conform to VMS naming conventions. 

• $DS_$DECIMAL, $DS_$OCTAL, $DS_$HEX, $DS_$STRING, 
$DS_$LOGICAL — Each of these macros is used to obtain 
hardware parameters from the user when an ATTACH command 
is typed. The exact macro to use depends on the format in which 
the input stiring of the particular parameter is to be interpreted. For 
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example, the $DS_$DECIMAL macro should be used if the user is 
to tj^e a decimal number, and the $DS_$STR1NG macro is used 
if an alphabetic string is to be tj^ped. For each of these macros, 
the programmer specifies a user prompting message. Information 
is read from the ATTACH command line and stored in the value 
register. 

• $DS_$STORE, $DS_$ADD, $DS_$FETCH - These macros are 
used to manipulate data that was received from a $DS $DECIMAL, 
$DS_$OCTAL, $DS_$HEX, $DS_$STRING, or $DS_$LOGICAL 
command and placed in the value register. $DS_$STORE will 
place the value register's contents into a field within the p-table. 
$DS_$ADD will add the value register's contents to the current 
contents of a field. $DS_$FETCH will retreive data from a field and 
place it, right-justified, in the value register. 

• $DS_$COMPLEMENT, $DS_$CASE, $DS_$L1TERAL - These 
macros are used to alter the contents of the value register. 

• $DS_$END - The $DS_$END macro is used to indicate the end of 
a p-table descriptor. 

Example 3-3 shows the p-table descriptor for the KDB50 controller. 
It will supply the p-table with the necessary device-dependent and 
device-independent information. 



Example 3-3 P-Tabie Descriptor for KDB50 Controller 


.MACRO $DS_KDB50 






Name the macro. 


$DS_KDB50_DEF 






Include device-dependent fields 


$DS_$INITIALIZE 


KDB50,HP$K_KDB50_ 


LEN ; 


Supply the device type, 
length of p-table. 


$DS_$Name 


Ptd$M_Controller, 


DU ; 


Supply format for device 
name validation. 


$DS_$FETCH 


HPSA_DEVICE,25,7 




Get BI space base address 
from the device-independent 
field, HP$A_DEVICE 
(See section 3.2.2) . 


$DS_$CASE 


«0,"X30» 




If Scorpio, make it 60000000. 


$DS $STORE 


HP$A_DEVICE,25,7 




Save BI base. 


$DS_$STORE 


HP$A_DVA,25,7 




Save BI base. 


$DS_$LITERAL 


<^X1> 




Start of BI window space. 


$DS~$STORE 


HP$A_DVA,22,1 






$DS_$HEX 


<BI Node Number (HEX)>,0 


,F ; Generate message requesting 


$DS~$STORE 


HP$B_KDB5 0_NODE_ I D 


,0,8 


; the BI node id and then store 


$DS_$STORE 


HP$A_DEVICE,13,4 




; it an 4 fields of the p-table; 


$DS_$STORE 


HP$A_DVA, 18,4 




; node id, adapter device 
; register, adapter address 


$DS_$STORE 


HP$W_VECTOR,2,4 




; space and the adapter vector. 


$DS_$LITERAL 


<'^X5> 




; KDB50 fixed at BR 5. 


$DS~$STORE 


HP$W_VECT0R,6,3 




; Store in the adapter vector 


$DS_$STORE 


KDB50$B_BR,0,8 




;& the bus request level fields. 


$DS_$FETCH 


HP$A DEVICE, 0,32 




; Store base address of UNIBUS 


$DS~$STORE 


HP$L_KDB50_IP, 0, 32 




; CSR in the Init/Poll field. 


$DS_$LITERAL 


<'"XF2> 




; Offset this address by '"XF2 


$DS_$STORE 


HP$L_KDB50_IP,0,8 




; (Store in low byte). 


$DS~$LITERAL 


<'^X0> 




; Clear the burst data 


$DS_$STORE 


HP$B_KDB50_BORST, 


8 


; transfer rate. 


$DS_$END 








. ENDM $DS_KDB50 
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Note that some fields of a p-table created from this descriptor require 
several steps. For instance, the HP$A_DEVICE field is constructed by: 

• Setting the high order four bits to 6 (bit 30 indicates PI space and bit 
29 indicates VAX I/O addresses). 

Note: This is an important step to remember. The VDS maps PI addresses 
to I/O space when memory management is enabled. Therefore, device 
addresses must be constructed as virtual addresses in PI space. This 
field will have been initialized by the VDS with the HP$A_DVA field 
of the link device. For 82XX/83XX systems, the Imk is HUB, and 
therefore the HP$A_DEVICE field is and must be initialized by the 
p-table descriptor. 

• Using the node id to set bits 13 through 16, which will select the 
address space for the indicated BI node. 

• In this case the contents of HP$A_DEVICE are copied into HP$A_DVA, 
and bit 10 of HP$A_DVA is set. 

Example 3-4 is the dialogue generated by the VDS. The furst 3 prompts are 
generated every time the ATTACH command is used; the last prompt is 
device-specific and is defined by the p-table descriptor for the KDB50. 

Example 3-4 Sample ATTACH Dialogue 

DS> ATTACH 

Device type? KDB50 

Device Link? DWMBR2 

Device Name? DUG 

BI Node Number (HEX)? 5 



3.2.3.3 Creating Names for Device-dependent Fields 

For easy reference, all device-dependent fields of a p-table should be 
assigned mnemonics. These mnemonics can then be used by the p-table 
descriptor macros $DS_$STORE, $DS_$ADD, and $DS_$FETCH. Also, the 
diagnostic program can use the mnemonics when it references a p-table. 
The field naming conventions for p-tables follow the VMS standard for data 
structure naming conditions. The field name begins with the name of the 
data struchire (HP), followed by a dollar sign ($), followed by the data type 
specifier (L for longword, W for word, and so on, as Hsted in Table 6-1), 
followed by an underscore (_), followed by the field name. For example, 
the KDB50 BI adapter p-table has a device-dependent field for storing the 
node id. This field is named HP$B_NODE_ID. 

Note: Many p-table descriptors were developed before this standard was 

implemented. The previous standard was for field names to consist of 
the device name, dollar sign, data type, underscore, field name, as in 
'KDB50$B_NODE_ID. If the mnemonics for the device-dependent fields 
of a particular p-table do not match the current standard, they will conform 
to this old standard. 
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3.2.3.4 Location of P-Table Descriptors 

P-table descriptors generally reside in the VDS. When a diagnostic program 
is written to test a device for which the VDS does not possess p-table 
descriptors, it is the reponsibility of the diagnostic program developer to 
also create a p-table descriptor for the device. This descriptor will then be 
incorporated into the VDS. 

Note: It is important to work in cooperation with the VDS development group 
when creating a p-table descriptor. 

P-table descriptors may also be included in the diagnostic program. When 
processing an ATTACH command, the VDS will first check the diagnostic 
program to see if a p-table descriptor exists for the specified device t3rpe. 
If none exists, the VDS will check its own p-table descriptors to locate the 
appropriate one. Thus, a descriptor residing in a diagnostic program will 
have precedence over a descriptor for the same device residing within the 
VDS. 

Including p-table descriptors in a diagnostic program has several 
disadvantages: 

• The descriptors can only be used by the diagnostic program in which 
they are defined. 

• The devices they describe cannot be attached until the diagnostic 
program has been loaded. 

• These diagnostic programs are not executable under APT. 

• The autosizer program only supports devices for which the descriptors 
reside in the VDS. 

When development of a program for a new device begins, the p-table 
descriptor should first be placed in the diagnostic program until the 
descriptor design, and the design of the device hardware itself, has been 
finalized. Once the p-table's design is certain, it can be included in the 
VDS. Only in rare instances should it be necessary to release a diagnostic 
program that contains its own p-table descriptors. 



3.2.4 Referencing P-Tables from a Diagnostic Program 



A diagnostic program gains access to a p-table by using the $DS_GPHARD 
macro. The program indicates a unit number as an argument to the macro, 
and the VDS will pass the base address of the p-table for that unit to the 
diagnostic program. The program can then access fields within the p-table 
by using the base address and the predefined field mnemoruc offsets (see 
above). The $DS_GPHARD macro is discussed further in the description 
of initialization code (see Section 3.5). 
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Example 3-5 provides an example of referencing a p-table in a MACRO-32 
program. Notice that before the p-table field mnemonics can be 
referenced, the macros which define them must be called ($DS_HPODEF 
for the device-independent fields and in this case, $DS_KDB50_DEF for 
device-dependent fields). 

Example 3-5 Referencing a P-Table in a MACRO-32 Program 



$DS_HPODEF ; Define device-independent p-table fields 
$DS_KDB50_DEF ; Define KDB50 device-dependent fields 



LOG_ONITi 
PTABLE: 
DEV NAM; 



.BLKL 1 
.BLKL 1 

.ASCIC \KDB50\ 



; Storage for logical unit number 
; Storage for pointer to p-table 

; Ascii nsune of desired device 



INCL LOG_UNIT 
$DS_GPHARD_S DEVNUM=LOG_UNIT, 
ADEU.OC=PTABLE 





CMPL 


RO, DS$ NORMAL 




BNEQ 


40$ 


10$: 


MOVL 


PTABLE, R2 




MOVAL 


DEV NAM, RO 




CMPL 


(RO), HP$T TYPE(R2) 




BNEQ 


20$ 




CMPW 


4(R0), HP$T TYPE+4(R2) 




BEQL 


30$ 


20$: 


$DS ABORT ARG=TEST 


30$: 


MOVZBL 


HP$B NODE ID(R2), R3 




MOVL 


HP$L_KDB50_IP,R4 



Get PTABLE for next log. unit 

. . address in PTABLE 

If all units done 

then branch to re-init. 

Use R2 as structure pointer 

Set up pointer to type 

Check length and first 3 

characters of type. 
Check last 2 characters 
If it matches, OK 
If not KDB50, abort test 
Move 81 node id into R3 
Move UDA address into R4 



40$: 



Note: (This code is meant only to show an example of the use of p-table 

mnemonics. The function performed does not need to be included in 
a real diagnostic program.) 



3-16 



Core Components of a VAX/DS Diagnostic Program 



Example 3-6 is a BLISS-32 example of referencing a p-table. Notice 
that before p-table mnemonics can be referenced, a pointer must be 
declared (in this case called PTABLE) using the $DS_HPO_DECL macro 
including the field declaration for the device t5^e being tested (in this case, 
a KDB50). 

Notice that the HP$T prefix fields expand only to addresses. To do data 
fetches from these fields, explicit field references must be made (as in the 
example for HP$T_TYPE). 

Example 3-6 Referencing a P-Table In a BUSS-32 Program 



BEGIN 



LOCAL 

CSR ; REF VECTOR [, LONG], 

TEMP_ADDR : LONG, 

DEVICEUNIT ! WORD, 

STATUS ' Status return from service calls 

PTABLe': REF $DS_HPO_DECL ( $DS_KDB50_DEF) ; ! Address of PTABLE 

BIND ^ _, . 

DEV_NAM = UPLIT BYTE (%ASCIC' KDB50 ' ) ; ! ASCII name of device 



! ++ 

! Get the address of the p-table for the next logical unit number. 

! If the $DS_GPHARD call returns successfully, do the processing. 

I — 

LOG_UNIT = .LOG_UNIT + 1; 

STATUS = $DS_GPHARD (UNIT=. LOG_UNIT , I Get PTABLE 
RETADR=PTABLE ) ; 

IF .STATUS EQL DS$_NORMAL 

THEN 

BgQjN '■ $DS_GPHARD worked 

IF .(PTABLE [HP$T_TYPE]) NEQ .DEV_NAM ! Validate type 

OR .(PTABLE [HP$T_TYPE] + 4)<0, 16> NEQ .(DEV_NAM + 4)<0, 16> 

THEN 

$DS_ABORT (ARG = TEST); ! Abort test if wrong device 

NODE_ID = .PTABLE [HP$B_KDB50_NODE_ID] ; ! Get BI node id 
UDA_CSR = .PTABLE [ HP$L_KDB50_IP] ; 1 Get address of UDA CSR 



END 

ELSE 

Bggjfj ! $DS_GPHARD returned error. 



END 
END; 



Note: (This code is meant only to show an example of the use of p-table 

mnemonics. The function performed does not need to be included in 
a real diagnostic program.) 
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To reference a field in the extended part of the device-independent 
p-table section, declare a pointer to the extended p-table fields using 
$DS_HPEODEF, and compute the base address of the extended p-table 
(See description of HPE$A_EPB, Section 3.2.2. Example 3-7 is that portion 
of MACRO-32 code used to compute the base address of the extended 
p-table to access the drive number for an RA90 disk drive. 

Example 3-7 Computing the Base Address of the Extended P-Table 



$DS_GPHARD_S DEVNUM=LOG_UNIT, - 
ADRLOC=PTABLE 
10$: MOVL PTABLE, R2 

ADDL3 HP$W_SIZE(R2),R2,R3 

MOVL - ( R3 ) , R4 

MOVW HPE$W_EXT_DRIVB ( R4 ) , R5 



Get PTABLE for next log. unit 

. . address in PTABLE 

Use r2 as structure pointer 

Move size of p-table into R3 

Compute end of extended p-table 

Address of EPB stored here 

Accessing drive number field in EPB 



3.2.5 Attaching from Within the Diagnostic Program 



It may occasionally be necessary for a diagnostic program to explicitly 
attach a device instead of depending on the program user to issue an 
ATTACH command. An example of this is the autosizer. 



3.3 Diagnostic Program Global Data Structures 



The data structures described here are used to pass information about the 
diagnostic program to the VDS. 



3.3.1 Diagnostic Program Header 



The diagnostic program header is a data block containing various types of 
information needed by the VDS, such as the program's title and pointers 
to the various areas of the program that the VDS must call during program 
execution. 

The header is allocated by using the $DS_HEADER macro, and must be 
located at the beginning of the program. It is the first (lowest) area of 
memory allocated to the program. When the program is loaded by the 
VDS, the header's first address will be location 200 (hex). 

Some header entries must be initialized at assembly time using macro 
arguments. Other entries are supplied by the linker. The diagnostic 
program should not alter or reference any header entries during program 
execution. 
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3.3.2 Dispatch Table 



The dispatch table is the means by which the VDS dispatches program 
control to the various tests in the diagnostic program. The table consists of 
a list of addresses of the tests. 

The dispatch table is defined by the $DS_DISPATCH macro. The table's 
entries (test addresses) are generated when the diagnostic program is 
linked. 



3.3.3 Program Sections Table 



The program sections table contains character strings defining the names of 
the program sections (see Section 3.8.3), as well as pointers to the sections. 

The VDS uses this table when the user specifies a section name with a 
RUN or START command, in order to determine if the specified section 
exists and where it is located. 

The program sections table is defined with the $DS_SECTION macro. 



3.3.4 Device Mnemonics List 



The device mnemonics list is the means by which the VDS determines 
what types of devices the diagnostic program is capable of testing. When 
a RUN or START command is issued by the user, the VDS compares the 
device t5^es in the device mnemonics list against the types of the selected 
devices (see the VAX/DS Diagnostic Supervisor User's Guide) to determine if 
there are any selected devices that the program can test. The list has two 
kinds of entries. Entries cem either be addresses of counted ASCII strings 
or addresses of p-table descriptors. 

For device tj^es having p-table descriptors defined within the VDS, 
the device mnemonics list entry will be the address of an ASCIC string 
representing the device type (for example, KDB50 and RA90). 

For device t3^es having p-table descriptors defined within the diagnostic 
program, the device mnemonics list entry will be the address of the 
device's p-table descriptor. 

The device mnemonics list is created and formatted by the $DS_DEVTYP 
macro. 



3.4 Program Passes and Subpasses 



Most diagnostic programs contain several tests (see Section 3.8). It is 
common for a system-under-test to have several xmits of the t3^e of device 
being tested. 

One complete execution of all selected tests on all selected units is one 
program pass. 

One complete execution of all selected tests on one selected unit is one 
subpass. 
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For a diagnostic program using serial testing (see Chapter 1), each pass will 
consist of one or more subpasses. For a diagnostic program using parallel 
testing (see Chapter 1), each pass will contain only one subpass since all 
devices are tested concurrently. 



3.5 Initialization Code 



Prior to the execution of a group of tests on a particular device, the 
diagnostic program must perform some initialization functions. These 
functions include obtaining the address and other characteristics of the next 
unit to be tested, creating a data path to the device, and initializing program 
buffers and counters, which are placed in a portion of the diagnostic 
program known as the initialization code. This code is delimited by the 
macros $DS_BGNINIT and fDS.ENDINIT. The VDS will dispatch control 
to this code at the beginning of each program subpass, before calling any 
of the tests. 



3.5.1 Format of tiie Initialization Code 



The format of the initialization code depends on whether the diagnostic 
program performs serial testing or parallel testing of the units. For serial 
testing, one unit will be initialized each time the initialization code is 
executed. The VDS will dispatch control to each selected test and then call 
the initialization code again so that the next unit may be initialized. For 
parallel testing, each execution of the initialization code should cause all 
units to be initialized. 

When the VDS calls the tests, all units will be tested at once. (Note that the 
VDS itself does not operate differently when parallel testing occurs instead 
of serial testing. The initialization code determines the type of testing to be 
performed by initializing only one device at a time for serial testing, or all 
devices simultaneously for parallel testing.) 



3.5.2 Services Used by the Initialization Code 



The $DS_GFHARD service is very important in the initialization code. 
This macro will pass the address of a p-table to the diagnostic program. 
The program will then use the device parameters stored in the p-table to 
determine how to reference the device. 

For level 3 (standalone mode) programs, initializing a unit involves 
executing the $DS_GPHARD macro to get a unit's p-table address, and 
then executing the $DS_CHANNEL macro to initialize the appropriate bus 
adapter. The $DS_SETMAP macro may also be used in the initialization 
code. (Both the $DS_CHANNEL and $DS_SETMAP macros may also be 
used within the actual tests.) 

For level 2R (user mode) programs, imit initialization will consist of 
executing the $DS_GPHARD macro to obtain the unit's p-table address, 
followed by issuing the SASSIGN system service. Device allocation (using 
the SALLOCATE system service) is requested by the VDS if the p-table 
descriptor for the device indicates that the device must be allocated (see 
Section 3.2.2). 
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3.5.3 Logical Units 



The initialization code must be written to handle an unspecified number 
of logical units since the nvimber of units will vary from system to system. 
At run-time, the VDS determines the number of units that can be tested 
by using the list of selected units (see the VAX/DS Diagnostic Supervisor 
User's Guide) and comparing it with the list of device tj^jes which may be 
tested by the diagnostic program (as contained in the Device Mnemonics 
List). One of the arguments to the $DS_GPHARD macro is the logical 
unit number (LUN). If this value is greater than the actual number of 
units which may be tested, the VDS will return from the $DS_GPHARD 
service routine with an error status. The initialization code can then 
contain a REPEAT-UNTIL loop that executes the $DS_GPHARD macro 
and increments the logical unit number until the macro's return status 
value indicates the error. 

It is important to note that the LUN argument to the $DS_GPHARD macro 
does not refer to the actual unit number of a hardware configuration. For 
example, consider a program that tests disks. Suppose this program is run 
on a system that has two controllers, each possessing one drive. Each of 
these drives could be imit on its respective controller. The logical unit 
number associated with the unit would depend on the order in which the 
drives were attached. Once the $DS_GPHARD service has been executed, 
the p-table for the logical unit number can be examined (specifically, field 
HP$B_DRIVE) to determine which unit has been associated with the logical 
unit number. 



3.5.4 Program Passes and the initialization Code 

When $DS_GPHARD rehirns an error status, indicating that the highest 
numbered logical unit has been tested, the initialization code must signal 
the VDS that one program pass has been completed. The $DS_ENDPASS 
macro is used for this purpose. This macro will call a VDS service that 
will update the count of passes executed and check to see if the number of 
requested passes has been executed. If so, the program's summary routine 
(see Section 3.7) and cleanup code (see Section 3.6) will be executed, and 
the VDS command line interpreter will be called. Otherwise, program 
control is returned to the diagnostic program's initialization code, which 
can reset the logical unit number to zero so that a new program pass can 
begin. 

Two other macros useful in the initialization code are $DS_BPASSO and 
$DS_BNPASSO. These macros are used to cause program branching 
depending on whether or not the first program pass is being executed. 
It is often necessary to perform special initialization the first time the 
initialization code is executed. For example, the location containing the 
number of the next logical unit to be tested must be initialized the first 
time through the code. Another example of a function that should only 
be performed the first time the initialization code is executed is volume 
verification (see Section 6.5.3). These macros are discussed in Section 3.11, 
Conditional and Unconditional Branching. 
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3.5.5 initialization Code Examples 



Examples 3-8 and 3-9 illustrate the necessary program steps in initialization 
code. 

Example 3-8 initialization Code for Serial Testing 



IF PASS 
THEN 



BEGIN 

! Program initialization 

ALLOCATE BUFFERS 

LOGICAL_UNIT_NUMBER=0 

END 



ELSE 



INCREMENT LOGICAL_UNIT_NUMBER 

IF ALL UNITS DONE 

THEN 

BEGIN 

! End of pass 
CALL $DS_ENDPASS 
LOGICAL_UNIT_NUMBER=0 
END 
! Per-pass code 
CALL $DS_GPHARD 
ASSIGN CHANNEL 
CLEAR BUFFERS 
CLEAR COUNTERS 



Example 3-9 Initialization Code for Parallel Testing 



IF PASS 
THEN 



BEGIN 

! Program initialization 

ALLOCATE BUFFERS 

END 



ELSE 



BEGIN 

! End of pass 

CALL $DS ENDPASS 
END 

LOGICAL_UNIT_NUMBER=0 
REPEAT 

$DS_GPHARD 

ASSIGN CHANNEL 

INCREMENT LOGICAL UNIT NUMBER 
UNTIL ALL UNITS DONE 
CLEAR BUFFERS 
CLEAR COUNTERS 
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3.6 Cleanup Code 



When all testing of a device has been completed, there must be a means 
for guaranteeing that the device is left in a known, initialized, static state. 
The "cleanup code" is provided for this purpose. This code resides in 
the diagnostic program, delimited by the macros $DS_BGNCLEAN and 
$DS_ENDCLEAN. 

The cleanup code will be executed under the following circvimstances: 

• The last program pass has been completed. 

• The diagnostic program has executed the $DS_ABORT macro. This 
macro should be used when a catastrophic feiilure is detected by the 
program. 

• The user has issued the VDS's ABORT command. 

• An exception condition has occurred and was handled by the VDS last 
chance condition handler (see Section 4.4.5, Condition Handling). 

• The program has been aborted because a $DS_ASKxxxx macro was 
executed with no user present and no default response. 

Cleanup code must perform the following functions. 

• Disable all device and adapter interrupts. 

• Deassign charmels if in user mode. 

• Deallocate memory buffers. 

• Cancel timers. 

• HALT all secondary processors on a multiprocessor system. 



3.7 Sumnfiary Routine 



The summary routine is an optional portion of the diagnostic program. 
It is used to display a summary of the program's execution history on 
the user's terminal. Summary routines are most likely to be included 
in programs that perform many repetitive functions and/or have long 
execution times, since these program are likely to compile large error 
counts. The summary routine will be called by the VDS at the end of the 
last program pass (unless the user has disabled the display with the BBS 
flag; see the VAX/DS Diagnostic Supervisor User's Guide). Additionally, the 
routine will be executed when the user issues the SUMMARY command 
(see the VAX/DS Diagnostic Supervisor User's Guide). 

When the SUMMARY command is issued, the VDS provides a generalized 
summary message whether or not the diagnostic program includes a 
summary routine. This message indicates the program name and the 
number of errors that were reported (see Section 3.9, Reporting Errors). 
An example of the message is as follows: 

Summary of EVRAD - LEVEL 2 DISK FUNCTIONAL TEST, Rev 1.1: 

1 program detected error (1 Hard, Soft, System, Device). 

Supervisor detected errors. 
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If a summaiy routine is included in the diagnostic program, the message 
generated by that routine is displayed with the above message. 

The summary routine is delimited by the $DS_BGNSUMMARY and 
$DS_ENDSUMMARY macros. All messages displayed with the summary 
routine must be printed by using the $DS_PRINTS macro. 

Tj^ically, the routine will contain code to display run-time statistics such 
as the total numbers of read transfers, write transfers, read errors, and 
write errors that have been detected on each unit being tested. Any 
other information relevant to the type of device being tested may also be 
displayed. 

A separate set of totals must be kept for each unit. It is useful to store 
these sets of totals in one large data area within the program, delimited by 
the $DS_BGNSTAT and $DS_ENDSTAT macros. 

3.8 Tests, Subtests, and Sections 



3.8.1 Tests 



All diagnostic programs contain one or more (usually several) tests. A test 
consists of code that examines a portion of the UUT. 

If the diagnostic program is a logic test, each test should be designed to 
check a subset of the UUT's logic. If the program is a function test, each 
test will check a subset of the total functionality of the device. The program 
designer will decide on the specific design, content, and number of tests, 
based on what is appropriate for the particular device. Each test must be 
free-standing. That is, proper execution of a test must not depend on the 
previous execution of any other test. Thus, any group of tests must be 
executable in all possible combinations and sequences. 

If several tests require a common segment of code, this common seqment 
may be made into a global routine called by each test. Global routines 
should be placed in a separate area of the diagnostic program, outside the 
boundaries of any particular test. 

Each test is delimited by the $DS_BGNTEST and $DS_ENDTEST macros. 

It may be desirable to execute the same test repeatedly, but using a 
different set of input arguments each time. This may be accomplished 
by grouping the various sets of input arguments together and delimiting 
them with the $DS_BGNDATA and $DS_ENDDATA macros. When this 
is done, the VDS will automatically execute the code within the test once 
for every set of arguments specified, before going on to the next test. From 
the user's point of view, this repeated execution of the code within the test 
will appear to be one execution of the test. 
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Tests should be composed of one or more of subtests. A subtest is a small 
section of code that performs one function. Each subtest must be delimited 
by the $DS_BGNSUB and $DS_ENDSUB macros. The $DS_BGNSUB 
macro automatically assigns a number to each subtest. Subtests are 
numbered from 1 to N for each test, where N is the total number of 
subtests within the test. Subtests cannot be nested. It is not legal to branch 
from one subtest to another using GOTO-type instructions. Subtests 
may be either executed sequentially or called from a higher-level routine. 
Figure 3-5 illustrates legal and illegal program flow using subtests. 



Figure 3-5 Legal and Illegal Usage of Subtests 
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If several tests require the use of the same subtest, the code within the 
subtest (not including the $DS_BGNSUB and $DS_ENDSUB macros) can 
be placed in a global subroutine placed in a separate area of the diagnostic 
program, outside the bounds of any particular test. Then every subtest 
requiring the code can call the subroutine. 

Subtests are useful for the following reasons: 

• They define loop boundaries for the loop-on-error facility. Refer to 
Section 3.10, Looping, for a discussion of loop boundaries and looping 
on errors. 



They provide a means by which the program user can execute a small 
portion of a test. The user can use the VDS command language to 
cause the diagnostic program to be executed up to and including a 
particular subtest, with the option of looping on the subtest. Refer to 
the VAX/DS Diagnostic Supervisor User's Guide. 
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3.8.3 Sections 



A section is a group of tests. Sections are defined for the convenience of 
the program user. If the user specifies that a certain section of the program 
is to be executed, all the tests assigned to that section are automatically run. 
The user does not need to specify a long string of test numbers manually. 

The programmer should assign tests which perform similar functions to 
a section. The number, names, and purposes of a particular program's 
sections are the programmer's option, but the program should consider 
which groups of tests a user might wish to run as a set and create a section 
for that set. A test may belong to any number of sections. 

Sections are defined by using the $DS_SECTION and $DS_SECDEF 
macros, and by including the section name as arguments to the 
$DS_BGNTEST macro. These macros indicate to the VDS which tests 
should be associated with which sections. Every program has a default 
section called DEFAULT. The contents of this section depend on the 
particular program application and are generally specified by the program's 
user community. However, no test within the default section can require 
any sort of manual intervention, such as edtering switch positions and 
adding cables. The default section may ask for keyboard responses using 
the $DS_ASKxxxx macros (see Section 4.2.2.2, Prompting the User), but 
all $DS_ASKxxxx macros included in the default section must provide 
default responses. This will ensure that the default section will execute to 
completion if the VDS control flag OPERATOR is clear, indicating that no 
operator (user) is present. 

If any tests in the diagnostic program require manual intervention, these 
tests must be grouped together in one section. This section should be 
called MANUAL. The manual section MUST test for the presence of 
an operator by using the $DS_BOPER or $DS_BNOPER macro (see 
Section 3.11, Conditional and Unconditional Branching). If an operator 
is not present, each test in this section must call the $DS_ABORT macro. 



3.9 Reporting Errors 



The VDS provides extensive capabilities, via macro calls, for reporting 
detected error conditions. All error conditions must be reported by using 
the VDS macro calls. Error macros have the format $DS_ERRxxxx, as 
indicated later in this section. 



3.9.1 Error Message Formats 



The error macros call VDS services that will cause error messages to be 
displayed on the user's terminal. Error messages are divided into three 
sections or levels, so users can use VDS control flags to select or inhibit the 
display of all or part of a message, as discussed in Section 3.9.2. 

The first level is referred to as the message header. Part of this header is 
generated automatically by the VDS and identifies the current test, subtest, 
unit, and error. The rest of the header consists of a message specified by 
the programmer as an argument to the $DS_ERRxxxx macro. This last part 
of the message is a short statement identifying the t3^e of error. 
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The second level is provided by the programmer via the $DS_PRINTB 
macro, and is used to provide a clear statement of what the error is. For 
example, if a particular register's contents are tested and found not to 
be as expected, this level would be used to display the expected and 
actual contents of the register. The third level, also provided by the 
programmer (this time by using the $DS_PRINTX macro), can be a detailed 
error description, including such variable data as device register dumps 
and buffers of sent versus received data patterns. This level is used for 
dumping out large amounts of auxiliary information. 

The $DS_PRINTB and $DS_PRINTX macros that are used to generate the 
second and third message levels are contained in a subroutine referred to 
as an "error reporting routine." When the address of an error reporting 
routine is passed to an error macro ($DS_ERRxxxx), the VDS will cause 
the routine to be executed after the message header (first level) has been 
displayed. 

Details on specifying error messages are given in the description of the 
individual error macros ($DS_ERRxxxx) in Chapter 5. 

Example 3-10 shows a typical error message. In this example, the first 
three lines comprise the message header. The second half of the third line 
was specified by the programmer; the rest of the header (plus the last line 
of the message) was generated by the VDS. The remaining portions of the 
message were generated by an error reporting routine. In this example, 
only the $DS_PRINTB macro would be used within the error reporting 
routine. 

Example 3-10 Sample Error Message Using $DS_PRINTB 

******* ECKAX - VAX 11/750-specific CPU Cluster Exerciser - 4.0 ******** 

Pass 1, test 8, subtest 2, error 2, 4-MAR-1983 09:04:30.04 

Hard error while testing KAO: Attempting to initialize TU58 controller. 

Incorrect number of bytes received. 

EXPECTED: CONTINUE flag = 1 

Unrecognizable packet received. 

ACTUAL: 00000092 (X) bytes beginning at OOOOBAOO 

******** End of hard error number 2 ********* 

Example 3-11 illustrates an error message in which both $DSPRINTB 
and $DS_PRINTX macros should be used. The first line following the 
3-line header should be displayed using $DS_PRINTB. The last part of the 
message displays the parameters of a $QIO service. Since this is a fairly 
long list of auxiliary information, it belongs to the third message level and 
hence should be displayed using $DS_PRINTX. 



3-27 



Core Components of a VAX/DS Diagnostic Program 



Example 3-1 1 



Sample Error Message Using $DS_PRINTB and 
$DS_PRINTX 



****** EVXBA - VAX Bus Interaction Program - 5.1 ****** 

Pass 1, subtest 1, error 5, 9-MAy-83 14:55:29.16 

System fatal error while testing TTGl; ERROR ON QIO COMPLETION 

ERROR ATTEMPTING TO WRITE TO TTGl; 

QIO COMPLETION STATUS WAS: NOPRIV 
_TTG1 QIO BLOCK PARAMETERS WERE: 



QIO_EFN: 


00000020(X) 


EVENT FLAG # 


QIO_CHAN: 


00000050(X) 


QIO CHANNEL # 


QIO_FUNC : 


0OO000OB<X) 


10$ WRITEPBLK FUNCTION 


QIO lOSB: 


0004E888(X) 


IQ5B ADDRESS 


QIO_ASTADR: 


00001069(X) 


ADDRESS OF AST 


QIO_ASTPRM: 


0004E8O0(X) 


VALUE OF AST PARAMETER 


QIO PI: 


00004C10(X) 


PI ARG VALUE 


QIO P2: 


00000005(X) 


P2 ARG VALUE 


QI0_P3: 


OOOOOOOO(X) 


P3 ARG VALUE 


QIO_P4 : 


OOOOOOOO(X) 


P4 ARG VALUE 


QIO P5: 


OOOOOOOO(X) 


P5 ARG VALUE 


QIO P6: 


0004E940(X) 


P6 ARG VALUE 



****** End of device fatal error number 5 ****** 



3.9.2 VDS Control Flags Associated with Error Reporting 

Several VDS control flags are associated with error reporting. These flags 
are lEl, IE2, IE3, HALT, and LOOP. (See the VAK/DS Diagnostic Supervisor 
User's Guide for a complete discussion of VDS control flags.) 

The lEl, IE2, and IE3 flags control error message displays. If the lEl flag 
is set, the entire error message will not be displayed. If the user sets the 
IE2 flag, message levels 2 and 3 are not displayed; if the IE3 flag is set, 
message level 3 is not displayed. 

If the user has set the VDS control flag HALT to activate halt-on-error, the 
VDS will stop execution of the diagnostic program after the error message 
has been printed. If the VDS control flag LOOP has been set, the VDS will 
begin executing a program loop after the error message has been executed 
(see Section 3.10, Looping). 



3.9.3 Error Types 



Error conditions are divided into five classes, depending on their severity. 
A macro is provided for each class. The five error classes are preparation 
errors, soft errors, hard errors, device-fatal errors, and system-fatal errors. 



3.9.3.1 Preparation Errors 

Preparation errors are not hardware faults, but result when the program 
user has not properly prepared the UUT for testing. For example, a 
particular diagnostic program may require that a disk drive be write- 
enabled by the user. If the program finds that the user has not write- 
enabled the drive, it can declare a preparation error. The program could 
then run only those tests that do not requure writing to the UUT, or it could 
skip the urtit altogether. 
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Preparation errors are declared by using the $DS_ERRPREP macro. This 
macro may be issued from any point within the diagnostic program except 
the cleanup code. 



3.9.3.2 Soft Errors 

A soft error is one that you can recover from. That is, it is an error which 
may go away if the operation that detected the error is repeated. In an 
operating system, this type of error probably would not be reported to the 
user, but in a diagnostic program it is important to flag all errors whether 
or not they can be recovered so that the operation can be completed. An 
example of a soft error might be the occurrence of a write-check error when 
writing data to a medium. (It may be the medium that is bad, and not 
the device.) When a soft error is detected by the diagnostic program, the 
error should be reported and the operation reexecuted. However, there 
is generally a maximum number of retries that should be allowed. If the 
maximum is reached, a hard error (see below) should then be declared. 

The macro to use when reporting a soft error is $DS_ERRSOFT. This macro 
can only be issued from within tests (see Section 3.8.1). 



3.9.3.3 Hard Errors 

You cannot recover from a hard error. That is, it is an error so serious that 
the operation being performed cannot be completed. Such an error might 
be a disk seek error. A hard error should also be declared if an operation 
detected a soft error and the operation was retried unsuccessfully several 
times. If, for example, a routine performing write operations on a disk 
detected several write-check errors (which are soft errors), a hard error 
should be declared. 

Hard errors are reported by using the $DS_ERRHARD macro. This macro 
can only be issued from within tests (see Section 3.8.1). 



3.9.3.4 Device-Fatal Errors 

Sometimes a diagnostic program detects so many hard errors on a 
UUT that it is pointless to continue testing the device. Perhaps there is 
something so seriously wrong with the device that it cannot be tested at 
all. Or maybe an attempt has been made to test a nonexistent unit. In 
any of these cases it is appropriate to declare a device-fatal error, which 
indicates to the user that the program intends to stop attempting to test the 
UUT in question. Whenever a device-fatal error is declared in a program 
performing serial testing, the program should leave the current test (by 
issuing the $DS_EXIT macro). Additionally, an internal flag could be set to 
indicate that a fatal error has been declared. Each test could check this flag' 
and, if set, immediately issue the $DS_EXIT macro. In this way, no more 
testing would be performed on the unit (for this pass). The initialization 
code would reset the flag to allow testing of the next unit. 

The macro for declaring device-fatal errors is $DS_ERRDEV. This macro 
may be issued from anywhere within a diagnostic program except the 
cleanup code. 
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3.9.3.5 System-Fatal Errors 

A system-fatal error is one so serious that the diagnostic program cannot be 
executed at all. In user mode, for example, a system-fatal error should be 
declared if the user's process does not possess VMS privileges necessary 
to perform functions required by the diagnostic program (such as PHYSIO 
for a program that uses physical I/O; refer to the VAX/VMS System Services 
Reference Manual.) Any time a system-fatal error is declared, the diagnostic 
program should subsequently execute the $DS_ABORT macro to abort 
program execution. 

The macro for system-fatal errors is $DS_ERRSYS. This macro may be 
issued from anywhere within a diagnostic program except the cleanup 
code. 



3.10 Looping 



The VDS facility that is probably the most useful to repair technicians is 
program looping. Program loops, often called scope loops, because they 
aid the technician in tracing signals with an oscilloscope, are enabled when 
the technician sets the VDS control flag LOOP (see the VAX/DS Diagnostic 
Supervisor User's Guide). Once this flag has been set, a loop will begin 
executing any time an error macro ($DS_ERRxxxx) is issued. 



3.10.1 Defining Loop Boundaries 



Although actual execution of program loops is initiated automatically by the 
VDS, it is the responsibility of the programmer to define the boundaries of 
the loops. 

Each loop will have a lower bound and an upper bound. There will be at 
least one call to an error macro within these bounds. Whenever an error 
macro is serviced with the LOOP flag set, the VDS begins execution of the 
loop. Loop execution proceeds in the following sequence. 

1 After servicing the error macro call, the VDS returns program control 
to the instruction immediately following the error call in the diagnostic 
program. 

2 The diagnostic program continues execution imtil the loop's upper 
bound is reached. 

3 From the upper bound, the VDS causes program control to branch to 
the loop's lower bound. 

4 Execution of the diagnostic program continues until the upper bound is 
reached again, regardless of whether or not the error macro is issued 
again. 

5 The cycle is repeated. 
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Note that once the cycle is started through the execution of an error macro, 
the macro may or may not be executed on subsequent passes through the 
loop. This means that the loop will continue to execute even if the error 
condition disappears. In fact, once a program loop has been initiated, it 
will continue to execute indefinitely until a control-C is typed on the user's 
terminal. 

Loop boundaries may be defined explicitly by the programmer. If they 
are not, default values will then be used. For tests containing subtests, the 
default lower and upper bounds are the $DS_BGNSUB and $DS_ENDSUB 
macros of the subtest containing the error macro that was executed to 
report the error condition. The programmer can explicitly define loop 
boundaries by using the $DS_CKLOOP macro. This macro is placed after 
an error macro, but before the next $DS_ENDSUB or $DS_ENDTEST. If 
the the $DS_CKLOOP macro is contained within a test that consists of 
subtests, it must be placed within the bounds of a subtest. The macro 
takes the name of a program label as an argument. This label must be 
located before the error macro, but after the most recent $DS_BGNSUB 
or $DS_BGNTEST. The result is a loop whose lower bound is the label, 
and whose upper bound is the $DS_CKLOOP macro itself. Figure 3-6 
illustrates the various loop boundaries. 

Figure 3-6 Examples of Loop Boundaries 
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3.10.2 Characteristics of Loops 



Loops should be small. Each loop should generate a minimum amount of 
electrical activity on the UUT. The less activity that is occurring, the easier 
it will be for the technician to trace relevant signals. 

Loops must be made up of code that is repeatable. There is no point in 
creating a program loop unless the code within that loop can be executed 
repeatedly. The code must cause the same electrical activity to occur each 
time it is executed. For example, a loop that just sets a bit is useless, 
because the bit will be set the first time through the loop, and subsequent 
passes through the loop will cause no changes to take place. A loop 
that sets and then clears the bit would be appropriate. In order to make 
a loop's code repeatable, it may occasionally be necessary to alter the 
program flow within the loop after the first pass through the loop. The 
$DS_INLOOP macro can be used to determine if a loop is being executed. 
Branching within the loop can be performed depending on the return 
status from this macro. This macro is useful in places where severe errors 
occur. Ordinarily, the programmer may want to abort the program (using 
the $DS_ ABORT macro). However, if a loop is present, it may be desirable 
to branch around the $DS_ ABORT macro to allow the loop to continue. 

Caution should be practiced when branching within subtests containing 
$DS_CKLOOP macros. It is important not to branch past the 
$DS_CKLOOP macro or the loop could be broken. For example, suppose 
a loop is being executed, with a $DS_CKLOOP macro as the loop's upper 
bound. Suppose now that a section of code within the loop tests for a hard 
error condition and then branches around a $DS_ERRHARD macro if the 
error does not exist. If the branch goes past the $DS_CKLOOP macro, the 
loop will be broken. Illustrations of proper and improper branching within 
loops are shown in Figure 3-7. 

Figure 3-7 Proper and improper Branching Within Loops 
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3.10.3 Nesting Loops 



Loops whose boundaries are defined with the $DS_CKLOOP macro 
may be nested. Figure 3-8 illustrates nesting of loops. In Example A 
of Figure 3-8, loop 2 and loop 3 are contained in loop 1. In Example B, 
loop 3 is contained within loop 2, and loop 2 is contained within loop 1. 

Figure 3-8 Nesting Loops 



EXAMPLE A 



LABEL1: 

LABEL2: 

error macro 2 
$DS_CKLOOP LABEL2 . 
LABELS: 
error macro 3 
SDS_CKLOOP LABEL3 
error macro 1 
$DS_CKLOOP LABEL1 



> LOOP 2 



>L00P 1 



>L00P3 



EXAMPLE B 


LABEL1; 


LABEL2: 


LABEL3: 






1 LOOP 3 


error macro 3 




$DS_CKL00P LABEL3 




error macro 2 


$DS_CKL00P LABEL2 


error macro 1 


$DS_CKL00P LABEL1 





> LOOP 2 



)loop 1 



ZK-4782-85 



When loops are nested, the VDS always executes the smallest loop 
containing the issued error macro. If error macro 2 was issued in Example 
B, loop 2 would be executed. 

The VDS will always execute the loop containing the most recently issued 
error macro. In Example A, suppose error macro 1 was issued. This would 
cause loop 1 to begin executing. Suppose at a later point in time that error 
macro 2 was executed for the first time (perhaps because of an intermittent 
hardware failure). Then loop 2 would begin execution and loop 1 would be 
forgotten. 
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3.10.4 User-Specified Looping 



There is a method by which the user can request a loop to be executed 
even though an error macro has not been issued. The /TEST, /SUBTEST 
and /PASSES qualifiers on the RUN and START commands (see the 
VAX/DS Diagnostic Supervisor User's Guide) can be used to specify a test or 
subtest on which the user wishes looping to occur. When the specified 
test or subtest is reached, looping begins on that portion of code. The 
programmer should keep this feature in mind as subtests and tests are 
designed. 



3.11 Conditional and Unconditional Branching 



The VDS provides several macros to facilitate conditional branching within 
the diagnostic program. 

$DS_BERROR, $DS_BNERROR 

The "branch if error" and "branch if no error" macros can be used 
immediately after macros that call system services. The services will return 
a status indication (in RO), and these macros cue on that status. The macros 
accept as an argument the address to which the program should branch. 

$DS_BCOMPLETE, $DS_BNCOMPLETE 

The "branch if complete" and "branch if incomplete" macros are also 
used immediately following macros that call system services. Their 
function is the inverse of that of the $DS_BERROR and $DS_BNERROR 
macros. That is, $DS_BCOMPLETE is equivalent to $DS_BNERROR and 
$DS_BNCOMPLETE is the same as $DS_BERROR. Choosing one set of 
macros over the other is simply a matter of readability in the source code. 
For some system services, it makes more sense to branch if the service 
completed successfully, while for others it is more appropriate to branch if 
there was no error. 

$DS_BOPER, $DS_BNOPER 

The "branch if operator present" and "branch if operator not present" 
macros can be used anywhere in the diagnostic program. They cue on the 
setting of the OPERATOR flag (see the VAX/DS Diagnostic Supervisor User's 
Guide). They make it possible to execute or skip certain segments of code, 
depending on whether a user is or is not present. 

$DS_BQUICK, $DS_BNQUICK 

The "branch if QUICK flag set" and "branch if QUICK flag not set" 
macros can be used an3nvhere in the diagnostic program. They cue on 
the setting of the QUICK flag (see the VAX/DS Diagnostic Supervisor User's 
Guide). These macros allow you to create a "quick mode" in your program. 
This mode is selected optionally if the user sets the QUICK flag. 

Quick mode provides a fast program pass that does not perform thorough 
testing and is used when the user is more interested in a fast run-time 
than in careful, complete fault detection. The macros can be used to skip 
around segments of code in quick mode. Determination of what segments 
of code should be included or excluded in quick mode depends on specific 
program requirements. 
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$DS_BPASSO, $DS_BNPASSO 

The "branch if pass 0" and "branch if not pass 0" macros can be used 
when it is necessary to cause program flow to change, depending on 
whether or not the current program pass is the first one. The macros call 
a system service that returns a status indication (in RO) of whether or not 
the current pass is the first one, then an appropriate branch is generated. 
These macros are only to be used in the program's initialization code. 

$DS_ESCAPE 

The $DS_ESCAPE macro is used to exit from a test or subtest if an error 
has been detected within that test or subtest. It is used when it is pointless 
to execute the rest of the code within the test or subtest after the error was 
detected. For example, there is no point in executing write tests on a disk 
if it has been discovered that the disk is write-protected and a user is not 
present. 

If an error reporting macro ($DS_ERRxxxx) has been issued from within the 
current subtest or test, issuing an $DS_ESCAPE macro will cause program 
control to pass to the end of the subtest or test. $DS_EXIT 

The $DS_EXIT macro provides for unconditional branching to the end of a 
test, a subtest, an interrupt service routine, or the summary routine. This 
macro is often used in conjunction with the conditional branching macros, 
as in the following example: 

$DS BGNTEST 



$DS_BOPER 10$ 
$D5_EXIT TEST 
10$: 



$DS_ENDTEST 



OECLIT AA VAX FK.7A 

n^tic design guide 
VAX diagnostic 
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4.1 Introduction 



The previous chapter described components that must exist in every 
diagnostic program, such as initialization code and error reporting routines. 
This chapter describes components that are required only for particular 
diagnostic applications including input/output, memory management and 
allocation, sjmchronous and asynchronous events, file management, and 
multiprocessor issues. For detailed information regarding the VAX/DS 
macros and system services, see Chapter 5. 



4.2 Input/Output 



4.2.1 I/O with the Unit Under Test 



4.2.1.1 I/O in User Mode 

In user mode (level 2R programs), all input/output operations must be 
accomplished by using the VMS $QIO system service. The details of 
performing I/O operations with the $QIO service are described in the 
VAX/VMS I/O User's Guide, which must be read before developing a level 
2R program. 

Initiating I/O activity in user mode is a process involving three steps, each 
of which requires use of a VMS system service. 

1 Assign a channel to the device. 

A device cannot be referenced unless a channel that links the device to 
the program has been assigned to the user. A channel is a data path 
linking the device to the diagnostic program. Charuiel assignments 
are accomplished by using the $ ASSIGN system service. This service 
request should be issued from the diagnostic program's initialization 
code. 

When the diagnostic program has finished using the device, its 
channel should be deassigned by using the $DASSGN system service. 
This service should be requested in the program's cleanup code. 
Another useful VMS system service is the $GETCHN service that 
will provide information about the device attached to a specific 
channel. This information consists of the primary and secondary 
device characteristics as described in the VAX/VMS I/O User's Guide. 

2 Allocate the device. 

If the diagnostic program needs exclusive use of the device to be tested 
(no other users allowed to reference the device while it is being tested), 
the device must be allocated to the diagnostic program. Allocation is 
necessary if the program requires a scratch medium in the unit under 
test (UUT). If the program can use the currently loaded (nonscratch) 
device medium in a nondestructive manner, device allocation is not 
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necessary. Device allocation is not performed directly by the diagnostic 
program. Instead, the allocation request is issued by the VDS (via the 
$ALLOCATE system service) when the user types the VDS SELECT 
command (see the VAX/DS Diagnostic Supervisor User's Guide). The 
VDS determines whether or not to allocate the device by checking the 
HP$M_ ALLOC bit in the device's p-table (see Section 3.2.2, P-Table 
Format). If this bit is set (by the program developer who created 
the p-table descriptor; see Section 3.2.3, P-Table Descriptors), the 
$ALLOCATE service is requested. If the device cannot be allocated 
because it has already been allocated to someone else, the VDS informs 
the user. 

An allocated device will be deallocated (by the VDS issuing a VMS 
$DEALLOCATE service request) when the device is deselected or 
when the VDS EXIT command is typed. 

An instance when the diagnostic program might have to specifically 
allocate and deallocate a device is in the case of error logging (not 
VMS system error logging). If a level 2R program writes error logging 
data to a device, it may be necessary to allocate the device. In this 
case, the diagnostic program should use the VMS $ALLOCATE service 
within the initialization code. The cleanup code will have to use the 
$DEALLOCATE service to deallocate the device. Refer to the VAX/VMS 
System Services Reference Manual. 

Queue I/O requests. 

Actual input/output operations are requested by using the $QIO and 
$QIOW system services, which will place the request in an I/O queue. 
These services require a set of parameters to pass to the service routine. 
These parameters specify the following tj^es of information: 

a. The channel number on which the data transfer is to take place. 
The channel number is obtained from the VMS $ASSIGN service. 

b. The type of transaction desired. This is indicated by using I/O 
function encoding. 

I/O functions can be categorized into three groups, corresponding 
to the I/O methods (physical, logical, and virtual). The type of 
function to be used will depend on the type of device being 
tested and the type of diagnostic program being written (refer 
to Chapter 2). 

The function that is to be performed by a $QIO service is indicated 
by passing a 16-bit value to the service routine, which has the 
format illustrated in Figure 4-1. 

The function code is a 6-bit field indicating the type of I/O 
operation to be performed. Some function codes are device- 
independent, and others are device-dependent. Table 4-1 contains 
device-independent function codes for read and write functions in 
the three I/O transfer modes. 



4-2 



Additional Components of a VAX/DS Diagnostic Program 



The function modifier field is used to modify the operation 
specified by the function code. Bits within this field can be set 
in conjunction with the function code, and the $QIO service will 
alter the function to be performed accordingly. For example, the 
IO$_INHRETRY modifier can be used with an IO$_READVLBK 
function to inhibit retries when read errors are encountered. Refer 
to the VAX/VMS I/O User's Guide for a more detailed dicussion of 
I/O function encoding, along with tables of function codes and 
modifiers that are valid for each device supported by VMS. 

Figure 4-1 $QIO Function Code and Modifier Fields 
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Table 4-1 Device-Independent Read and Write Functions 

Physical I/O Logical I/O Virtual I/O 

IO$_READPBLK IO$_READLBLK IO$_READVBLK 

IO$_WRITEPBLK IO$_WRITELBLK IO$_WRITEVBLK 



The method by which the program is to be signaled that the 
I/O transaction has been completed. The desired method of 
determination is indicated with the $QIO service call. Three 
methods exist for synchronizing I/O completion: 

1 Waiting for an event flag 

The number of an event flag (see Section 4.4.2.) can be 
specified as an argument to the $QIO or $QIOW macros. 
This event flag will be set by the system service when I/O has 
completed. The diagnostic program can wait for the specified 
flag to be set (by using a system service). (The $QIOW service 
is a combination of the $QIO and $WAITFR services.) 

2 Testing an I/O status block 

The address of an I/O status block can be specified as an 
argument to the $QIO macro. The $QIO service will cause 
the first word of this block to be loaded with a status code 
when the I/O operation has been completed. The program can 
test the contents of the block to determine the status of the 
I/O operation. The format of an I/O status block is shown in 
Figure 4-2. 
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Figure 4-2 I/O Status Block Format 
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Refer to the VAX/VMS I/O User's Guide for more details about 
the contents of the I/O status block. 

3 Executing an AST routine 

The address of an as3nichronous system trap (AST) (see 
Section 4.4.3.) can be specified as a $QIO argument. An 
AST will be delivered (and the AST routine called) when the 
I/O operation has been completed. This method of determining 
I/O completion provides for the most asynchronous (and most 
efficient, in regard to processor usage) I/O activity. 

d. The address of a buffer which will receive diagnostic information. 
When a $QIO or $QIOW macro is issued, it is possible to request 
the system service routine to load a buffer with the contents of 
the device's registers. This diagnostic buffer will be loaded if the 
I/O transfer method is physical (see Chapter 2) and if the process 
possesses the "diagnostic" VMS privilege (see the VAX/VMS 
Command Language User's Guide). To request the system service to 
load the buffer, the programmer must: 

1 Define a buffer area within the diagnostic program. This buffer 
must be large enough to contain the contents of all the device's 
registers. 

2 Specify the address of this buffer as the "P6" argument to the 
$QIO or $QIOW macro (see Chapter 5). 

When the I/O operation has completed, the buffer will contain the 
final contents of the device registers, plus additional information. 
The format of the buffer's contents will generally be as indicated in 
Figure 4-3. 
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Figure 4-3 Typical $QIO Diagnostic Buffer Format 
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4.2.1.2 I/O in Standalone Mode 

In standalone mode (level 3 programs), I/O is performed by direct 
reference to the device's registers. Therefore, routines to initialize a 
device's control registers, service its interrupts, and check for error 
conditions must be contained within the diagnostic program. 

The diagnostic program must initialize the bus adapters so that a data 
channel can be created to transfer information across the buses. Because of 
the differences inherent in the bus adapters of the various VAX processor 
tjrpes, the VDS provides facilities for channel initialization that remove the 
burden of dealing with processor-specific details from the diagnostic 
programmer. This allows diagnostic programs to be automatically 
compatible with all VAX processor tjrpes. 

The VDS services, $DS_CHANNEL and $DS_SETMAP, are used to create 
data channels in standalone mode. The $DS_CHANNEL service is used 
to initialize the MASSBUS, UNIBUS, and VAXBI adapters. Depending on 
the parameters included with the $DS_CHANNEL macro, the service will: 

• Initialize the adapter 

• Clear the adapter 

• Enable or disable interrupts 

• Provide current adapter status 

Details are provided in the description of the $DS_CHANNEL macro in 
Chapter 5. 

The $DS_SETMAP service will set up the adapter's mapping registers so 
that data transfers will reference the desired areas of main memory. Details 
are provided in the description of the $DS_SETMAP macro in Chapter 5. 

The $DS_SHOCHAN service provides automatic display on the user's 
terminal of a bus adapter's internal registers. The configuration register 
and the status register are always displayed. If error conditions exist, 
additional registers will also be displayed. This macro should be used 
whenever the $DS_CHANNEL system service detects an error condition. 
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The address of the interrupt service routine (ISR) is passed to the 
$DS_CHANNEL service. Interrupt service routines in a diagnostic program 
should be delimited by the $DS_BGNSERV and $DS_ENDSERV macros. 
The VDS has an interrupt preprocessor that fields the interrupt initially, 
then dispatches control to the specified interrupt service routine. 

An interrupt service routine's function should be minimal, such as 
disabling further interrupts, confirming that the interrupt was expected 
(vectored correctly), and saving device status. Error reporting should not 
be done in an interrupt service routine unless it is to report unexpected 
interrupts. 

T3^ical program flow when using an interrupt service routine is as follows. 

• Main-Line Code 

Clear and initialize channel 
Set up I/O transfer 
Start watchdog timer 
Enable interrupts 
Clear done flag 
REPEAT 

Test done flag 
UNTIL done flag set OR watchdog timer finishes 
IF done flag set 

THEN cancel watchdog timer; report I/O status 
ELSE report timeout error 

• Interrupt Service Routine 

Disable interrupts 

IF unexpected interrupt (wrong vector) 

THEN set error status 

ELSE save device status 

Set done flag 

Return 

More information on interrupts can be found in the description of the 
$DS_CHANNEL service in Chapter 5. 

Other macros useful when performing I/O functions in standalone mode 



are: 



$DS_SETVEC — Stores the address of an ISR in a specified interrupt 
or exception vector in the system control block (SCB). This is the only 
method to modify the vectors in the SCB except in a multiprocessing 
environment in an attached process. Attached processes cannot use 
this service (see Section 4.6.8.1), and therefore must modify the SCB 
directly. 

$DS_CLRVEC - Restores the address of a VDS condition handler 
in a specified vector in the SCB. This is the only method to clear 
vectors in the SCB except in a multiprocessing environment in an 
attached process. Attached processes cannot use this service (see 
Section 4.6.8.1), and therefore must modify the SCB directly. 



4-6 



Additional Components of a VAX/DS Diagnostic Program 



• $DS_INITSCB — Reinitializes the system control block (SCB), which 
contains all of the interrupt and exception vectors to their standard 
(VDS-defined) values. Useful if several $DS_SETVEC macros have 
been used. 

• $DS_PROBE — Attempts to access an address to determine whether or 
not hardware (either memory or an I/O device) is connected to it. 

• $DS_SETIPL — Sets the processor's interrupt priority level (IPL) to a 
specified value. 



4.2.2 l/Owith the User Terminal 

All I/O between a diagnostic program and the user's terminal must be 
accomplished by means of VDS macros. Macros are provided to: 

• Display messages consisting of simple ASCII strings or a combination 
of ASCII strings and variable data 

• Prompt the user for a response; receive and store the response 

• Display the contents of a register and assign a mnemonic to each bit 

• Determine the user's terminal type and characteristics 



4.2.2.1 Message Display 

Message strings consisting of a combination of ASCII strings and data 
variables are displayed by means of the PRINT macros. This set of 
macros has the general form $DS_PRINTx. There are four print macros, 
known as $DS_PRINTB, $DS_PRINTX, $DS_PRINTF, and $DS_PRINTS. 
The $DS_PRINTB and $DS_PRINTX macros are used only to print 
error messages, and are used in conjunction with the error macros 
($DS_ERRxxxx). The VDS control flags used to inhibit error messages 
(see the VAX/DS Diagnostic Supervisor User's Guick) are closely associated 
to the $DS_PRINTB and $DS_PRINTX macros. The $DS_PRINTF macro is 
used when it is necessary to provide the user with information unrelated 
to error reports. The $DS_PRINTS macro is used for summaries (see 
Section 3.7, Summary Routine). 

The print macros are used to print simple ASCII strings, such as: 

DEVICE IS WRITE LOCKED. 

They can also be used to display the contents of data words or to print a 
combination of ASCII strings and variable data, such as: 

expected: 1010101010101010 (B) 
RECEIVED! 1011101010101010 (B) 
XOR: 0001000000000000 (B) 

Using a print macro involves specifying the address of a format statement 
and a list of variables. Format statements indicate the format in which 
the variables are to be printed. The method used by the print macros 
to format messages is the same as the $FAO system service proAnded by 
VMS. In fact, the $FAO service is also provided by the VDS. This service 
will format, but not print, a message. The print macros will both format 
and print the desired message. It is also possible to format a message with 
the $FAO service and then display it by using one of the print macros. 
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Another macro useful for displa5dng information to the user is 
$DS_CVTREG. With this macro, specify the address of a register and the 
address of a string of mnemonics. The mnemonics are the names assigned 
to the bits within the register. The macro will read the register and produce 
a character string showing which bits of the register are set. This string 
can then be displayed using one of the print macros. Details on the print 
macros are described in Chapter 5. The $FAO service is discussed in 
Chapter 5 and in the VAX/VMS System Sewices Reference Manual. 

It is sometimes useful to know the type and characteristics of the 
user terminal. For instance, you may want to format text displays 
differently on a video terminal from that of a hardcopy terminal. The 
$DS_GETTERM service may be used to determine the user terminal's type 
and characteristics. 



4.2.2.2 Prompting the User 

There are instances when it is necessary to solicit information from the 
user. A common example is the case in which the program must, at 
a certain point in its execution, ask the user to perform an action such 
as connecting a cable and to then type a response indicating that the 
action has been completed. Also, there may be circumstances when it is 
necessary to obtain additional information about the UUT (information 
which is not contained in the p-table). 

Note: It is important to try to place all device-specific information in the p-tables 
so that it can be specified in ATTACH commands before the diagnostic 
program is started. 

All solicitation of user responses during the diagnostic program's execution 
must be made through the use of the $DS_ASKxxxx macros. These macros 
allow the programmer to specify a prompting message, the format in 
which the user's response is to be interpreted, and a storage area for the 
response. 

Specifically, there are five $DS_ASKxxxx macros: 

• $DS_ASKADR — Prompts the user for an address within a specified 
range and stores the result. 

• $DS_ASKDATA — Prompts the user for a numeric value within a 
specified range and stores the result. 

• $DS_ASKVLD - Same as $DS_ASKDATA, except allows programmer 
to specify storage location of result as a field (using position and size) 
within a large bit structure. 

• $DS_ASKLGCL — Prompts the user for a Y (yes) or N (no) response, 
and stores the result as one bit, set or cleared. 

• $DS_ASKSTR — Prompts the user for a character string and stores the 
result. 
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The macros also allow the programmer to specify a default value for the 
response. If there is no user present (indicated by the state of the VDS 
control flag OPERATOR, see the VAX/DS Diagnostic Supervisor User's Guide), 
the default value will automatically be used. If no default value exists, the 
program will be aborted. Sometimes diagnostic programs require the user 
to specify run-time options other than those that can be selected using 
the VDS command language. In such cases, the $DS_ASKxxxx macros 
can be used to prompt the user for these required run-time parameters. 
One method of accomplishing this is to ask a set of questions that can be 
answered with Y (yes) or N (no), such as: 

DO YOU WISH TO RUN OPTION X? 

DO YOU WANT THE DEVICE TO RUN IN MODE Y7 

The responses to these question can be converted to set or cleared bits that 
the diagnostic program can test. This method is suitable when the total 
number of program options is small. 

However, for a program with a large number of run-time options, the 
program users might have to answer a large list of questions every time the 
program is executed (assuming they did not want to use the default values 
for these questions). In such cases, the programmer might want to just 
prompt the user once and allow him or her to type a string of options, as: 

OPTIONS ARE 0PTI0N_X, 0PTI0N_Y, OPTION_Z 
(DEFAULT IS 0PTI0N~X) 
TYPE OPTIONS! 

Allowing the user to type a list of the options wanted is more convenient 
for the user, even though it is more difficult for the programmer to check 
the strings typed to see if they are valid. 

For a program having a very large set of run-time options, it might be 
beneficial for the programmer to create a command language. An example 
might be: 

Coimnands: 

OPTIONS — select options 
MODES — select device modes 
BEGIN — begin program execution 
RESUME — continue after control-C 

The user would type the VDS RUN or START command to start the 
diagnostic program's execution. In the program's initialization code or 
within a particular test, the program executes $DS_ASKxxxx macros to 
prompt the user for command strings. The program parses and executes 
each command. The BEGIN command (or something similar) simply 
allows the VDS to continue normal dispatching of the diagnostic program. 
The RESUME command would be useful if a control-C handler is defined 
within the diagnostic program (see Section 4.4.6, Handling Control-Cs). 
The number and types of commands defined would, of course, depend 
completely on the particular diagnostic program being designed. 
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The VDS provides two macros to facilitate command parsing. The 
$DS_CLI macro is used to define the desired command language. The 
$DS_PARSE macro compares an input stream (obtained from the user via 
a $DS_ASKxxxx macro) and the command language defined with a set of 
$DS_CLI macros and will either dispatch to the proper action routines or 
inform the user if an illegal command has been typed. 



4.2.2.3 Displaying HELP Text 

Chapter 6 discusses the creation of HELP files, which are supplemental 
files containing informational text that the user can read. It may sometimes 
be desirable for the diagnostic program to fetch and display sections of the 
HELP file. This can be accomplished by using the $DS_HELP macro. Read 
Section 6.4.4, Help Files, and then refer to Chapter 5 for a description of 
the $DS_HELP macro. 

4.3 Memory Management and Allocation 

Memory management in the VDS is dependent on the current run-time 
environment: user mode or standalone mode. Discussions on memory 
management in both envirorunents are below. 

Note: The memory management hardware may not be directly referenced by 
diagnostic programs running under the VDS. 

For a discussion of VAX memory management, see the VAX Architecture 
Handbook. 



4.3.1 Memory Management in User Mode 



In user mode (level 2R programs), memory management hardware is 
under the control of VMS and it is always enabled. All of the VMS 
memory management system services are available for use by diagnostic 
programs. See the VAK/VMS System Services Reference Manual for the 
uses and restrictions applying to VMS memory management services. 
Allocation of new memory space should only be accomplished with the 
VDS $DS_GETBUF macro, as described in Section 4.3.3. 



4.3.2 Memory Management in Standalone Mode 



In standalone mode, the memory management hardware may be enabled 
or disabled; it is disabled by default. Unlike VMS, the VDS memory 
management will not increase the size of the virtual address space available 
to the diagnostic program. The memory management scheme in the VDS 
serves three functions: 

• Identify programming errors such as missing literal signs. For example, 
the MACRO-32 instruction MOVL 4,TEMP would generate an access 
violation when memory location 4 was read. 
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• Create two hardware test environments by using memory management 
as the variable. 

• Integrate the control of memory management within diagnostic 
programs which test the memory management hardware and the 
memory modules. 

Diagnostic programs may enable memory management with the 
$DS_MMON macro. Once enabled, it may be disabled with the 
$DS_MMOFF macro. Operators may enable and disable memory 
management with the SET MM ON and SET MM OFF commands. These 
commands override the $DS_MMON and $DS_MMOFF macros contained 
within a diagnostic program. Therefore, if a user has issued the SET 
MM ON command, the diagnostic program may not disable memory 
management with the $DS_MMOFF macro. 

Some diagnostic programs may not be able to execute if the memory 
management hardware is enabled. If this is the case, the $DS_MMOFF 
macro must be issued at the beginning of the program. If the status 
returned from this macro indicates that the operator has enabled memory 
management, the program must abort (with the $DS_ABORT macro), 
printing an appropriate error message before doing so. 



4.3.3 Memory Allocation 



Many diagnostic programs need extra memory space for I/O buffers or 
other uses. Additional memory space may be acquired by using the 
$DS_GETBUF macro. Both user mode and standalone mode programs 
should use this macro, since this method is the only way of ensuring 
that there will be no memory allocation conflicts between the VDS 
and the diagnostic program. The VDS manages all free memory. The 
$DS_GETBUF macro is used to request the VDS to assign a certain number 
of pages to the diagnostic program. The VDS will return the starting 
address of the memory space it has assigned. (Space will be assigned as 
a group of contiguous physical pages in standalone mode, and as a group 
of contiguous virtual pages in user mode.) When a diagnostic program 
is executing on a system possessing 512K b3^es of physical memory (the 
smallest memory size supported by the VDS), the program is guaranteed 
access to at least 96 kilobytes of buffer space. 

Memory space is returned to the VDS free memory pool by using the 
$DS_RELBUF macro. It is possible to change the protection of any page or 
group of pages by using the $SETPRT macro. 
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4.4 
4.4.1 



Synchronous and Asynchronous Events 
Introduction 



4.4.2 Event Flags 



A synchronous event is a condition that occurs as a direct resuh of the 
diagnostic program. Such events are predictable and, by definition, can 
only appear one at a time. Waiting for a bit to become set or creating a 
time delay are both examples of synchronous events. An asynchronous 
event is a condition that occurs independently of the diagnostic program. 
It is possible for such unpredicted events to appear simultaneously and in 
multiple numbers. VAX exceptions are asynchronous because they cause 
the normal flow of a program to be changed (program control is passed 
to the condition handler). Refer to the VAX Architecture Handbook for a 
detailed discussion of VAX exceptions. 

Most diagnostic programs must handle occxirrences of s)mchronous and 
asynchronous events. Event flags are useful for s5mchronous processing of 
events. AST routines and condition handlers are used for asynchronous 
processing. There are both S3mchronous and asynchronous methods 
available for handling time-critical situations. 



Event flags are all-purpose flags, provided by the VDS, that can be used by 
diagnostic programs to indicate status information. Services are provided 
for setting, clearing, and reading the flags. Additional services allow the 
diagnostic program to wait for a flag or group of flags to be set before 
proceeding with program execution. The services are called via macros. 
Whenever a new diagnostic program is loaded into memory by the VDS 
LOAD or RUN command, all event flags are cleared. 

There are 64 event flags, numbered from to 63. The flags are divided 
into two clusters, each containing 32 flags. Some event flag macros require 
that the cluster be indicated. 

Event flag is reserved for exclusive use by the VDS and is not available to 
diagnostic programs. 

Flags 1 through 23 can be set or cleared by the user via the SET EVENT 
FLAGS and CLEAR EVENT FLAGS commands, which means they can be 
used to implement user selection of optional program features. 

Flags 24 through 31 are used by VMS, and therefore cannot be used by 
level 2R diagnostic programs. They are available, however, to level 3 
programs. 

Flags 32 through 63 are available to all diagnostic programs. Users cannot 
modify these flags. 

In user mode (level 2R programs), event flags are maintained by VMS. The 
event flag macros call service routines within VMS. Event flags through 63 
are referred to as local event flags, since they can only be used internally 
by a single process. Another set of event flags, numbered from 64 through 
127, are referred to as common event flags since they can be shared by 
cooperating processes. The VMS system service $ASCEFC must be used 
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to associate common event flags with processes in order for these flags to 
be shared. See the VAX/VMS System Service Reference Manual for details. 

In standalone mode (level 3), event flags are maintained by the VDS, and 
the event flag macros call service routines within the VDS. 

The following macros are used in both level 2R and level 3 programs to 
reference event flags: 

$SETEF — Sets specified event flags. 

$CLREF — Clears specified event flags. 

$READEF — Read the current status of specified event flags. 

$WAITFR — Wait for a specified event flag to become set. 

$WFLAND — Wait for a group of event flags to become set. 

$WFLOR — Wait for one of a group of event flags to become set. 

$QIOW — Queue an I/O request and wait for a specified event flag to 
become set (indicating I/O completion). Equivalent to $QIO followed by 
$WAITFR. 

Additionally, the $SETIMR (see Section 4.4.4, Timing) and $QIO (see 
Section 4.2.1.1, I/O in User Mode) macros can optionally specify references 
to event flags. 



4.4.3 Asynchronous System Traps (ASTs) 



An asynchronous system trap (AST) is a software-simulated interrupt 
to a user-defined service routine (AST routine). ASTs enable the user 
process to be notified asynchronously with respect to its execution of the 
occurrence of a specific event. If an AST routine has been defined by the 
user, the system interrupts the process and executes the AST routine when 
that event occurs. The process by which AST routines are dispatched is 
called AST delivery. 



4.4.3.1 AST Delivery 

Four macros, available to both level 2R and level 3 diagnostic programs, 
facilitate the use of ASTs. These macros are $SETIMR, $QIO, $QIOW, and 
$DS_CNTRLC. Each of these macros will accept the address of an AST 
routine as an argument. The $SETIMR macro will cause the AST routine to 
be entered when the specified amount of time has elapsed. The $QIO and 
$QIOW macros cause the AST routine to be executed when the requested 
I/O operation has completed. The $DS_CNTRLC macro will cause an AST 
routine to be entered when the program user types a control-C. 

ASTs may be enabled or disabled with the $SETAST macro. If ASTs are 
disabled, ASTs will not be delivered and therefore the AST routines will 
not be executed. 

If a diagnostic program is waiting for an event flag (see Section 4.4.2, 
Event Flags) or hibernating (see Section 4.4.4, Timing), ASTs will still be 
delivered. After the AST routine has been executed, the program will be 
returned to the state it was in prior to the AST delivery (unless, the AST 
routine itself set the desired flag or woke the program). 

4-13 



Additional Components of a VAX/DS Diagnostic Program 



4.4.3.2 AST Routines 

An AST routine is entered via the MACRO-32 instruction CALLG. Thus, 
the routine must have an entry mask and must return by using RET 
instruction. It must save (by specifying them in the entry mask) any 
registers it uses, other than RO or Rl. 

When an AST routine is entered, the argument pointer (AP) points to an 
argument list in the format illustrated by Figure 4-4. The register values in 
the argument list are those saved when the main-line code was interrupted 
by delivery of the AST. The AST parameter is a value specified by the AST 
parameter argument of the macro ($SETIMR, $QIO, or $QIOW) used to 
request delivery of the AST. This argument can be used by the AST routine 
to determine from where it was called. 

Figure 4-4 Argument List Passed to an AST Routine 



4.4.4 Timing 



31 




8 7 








5 


AST PARAMETER 


RO 


Rl 


PC 


PSL 



Facilities are provided for creating timing delays within a diagnostic 
program. These facilities allow you to: 

• Specify a particular amount of time you wish to wait before proceeding 

• Cause the diagnostic program to stop executing until an expected event 
occurs 

• Cause an asynchronous event to occur after a specified amount of time 
has passed 

The timing facilities provided by the VDS compensate for speed 
differences among the various VAX process types. Therefore, all diagnostic 
programs containing time-dependent operations must use the VDS timing 
facilities in order to guarantee program compatabilify with all current and 
future processor types. 

The VDS timer services are accessed by macro calls. Some macros can 
be used for both level 2R (user mode) and level 3 (standalone) programs, 
while others may be used only for level 3 programs. 
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4.4.4.1 Timing Facilities Available in User IVIode and Standalone Mode 

The following is a list of macros that may be used by both level 2R and 
level 3 programs to control time-dependent functions. 

$GETTIM — Gets the current system time. 

$SETIMR — Allows you to cause an event to take place after a specified 
amount of time has passed. 

$BINTIM — Converts an ASCII string that specifies a time into a numeric 
value meaningful to the $SETIMR macro. 

$ASCTIM — Converts a time from numeric representation to an ASCII 
string. 

$CANTIM — Cancels requests specified with the $SETIMR macro. 

$HIBER — Causes processing to stop until an expected event occurs. 
Referred to as "hibernation." 

$WAKE — Cancels a $HIBER request. Referred to as "waking" the 
program. 

$DS_WAITMS — Delays sequential program execution for a specified 
number of milliseconds. 

$DS_CANWAIT - Cancels time remaining from a $DS_WAITUS or 
$DS_WAITMS call 

A typical use of these macros in standalone mode would be to issue a 
SSETIMR macro that will cause an AST routine (see Section 4.4.3) to be 
executed when the specified time has expired. Then a device's interrupts 
could be enabled. Some other processing could take place while waiting 
for the interrupt. When the interrupt occurs, the interrupt service routine 
could issue a $CANTIM macro to cancel the $SETIMR. If the interrupt does 
not occur before the time period ends, the AST routine would be entered. 
This routine could declare a timeout error. Program steps for this function 
would be as follows: 



TimeO 




Main Program: 


interrupt Service Routine: 


AST Routine: 






Issue $SETIMR macro. 










Enable Interrupts. 










Continue. 


Process interrupt. 

Issue $DS_CANTIM macro. 

Return from interrupt. 


IF interrupt does 
not occur within 
specified time 

THEN 
Set error flag. 






IF error flag set 




Return. 






THEN 










issue $DS_ERRxxxx macro 










ELSE 






V 




continue. 






TimeN 


(N 


>0) 
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4.4.4.2 Timing Facilities Available in Standalone Mode Only 

The following macro may be used only by level 3 programs. 

$DS_WAITUS — Delays sequential program execution for a specified 
number of microseconds. 

A typical use of this service would be to enable a device's interrupts, 
followed by a call to the SDS.WAITUS service to see if an interrupt 
occurred within a certain time frame. The interrupt service routine 
would set a flag to indicate that the interrupt occurred and would issue 
a $DS_CA]MWAIT to cancel any time remaining from the wait service. 
(Usually, the $DS_CANWAIT is optional and simply improves execution 
time by eliminating unnecessary time remaining in wait loops.) After the 
$DS_WArrUS call would be code to test the interrupt service flag. If the 
flag is set, the interrupt occurred. If not, the entire time delay was used up, 
indicating a time out condition. Program steps for this function would be 
as follows: 



Time 



iVIain Program: 



Interrupt Service Routine: 



Set up device for I/O. 

Enable interrupts. 

Issue $DS_WAITxx macro call. 

Test interrupt-occurred flag. 

IF flag not set 

THEN 

issue $DS_ERRxxxx macro 
ELSE 

continue. 



Process interrupt. 
Set interrput-occurred flag. 
Issue $DS_CANTIM macro. 
Return from Interrupt. 



Time N (N > 0) 



4.4.5 Condition Handling 



The VDS contains condition handling routines that will handle all exception 
conditions. It is therefore unnecessary under most circumstances for the 
diagnostic program to provide exception handling facilities. However, the 
VDS provides the ability for the diagnostic program to field exceptions 
when necessary. The VDS searches for condition handlers in exactly the 
same manner as VMS. As detailed in VMS documentation, handlers are 
searched for in the following order: 

1 If a primary handler exists, use it. 

2 If secondary handler exists, use it. 

3 Search call frames for address of handler. 

4 Use "last chance" handler. 
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If a handler is found, it can handle the condition and indicate a success 
(SS$_CONTINUE) return, or not handle the condition and indicate a 
resignal (SS$_RESIGNAL) return, which causes the handler dispatcher to 
continue to search for a handler. 

The VDS has a secondary condition handler, but it only services breakpoint 
(BPT) and trace (T-bit) exceptions associated the the VDS's breakpoint and 
single-step facilities (see the VAX/DS Diagnostic Supervisor User's Guide). 

The main condition handling facility of the VDS is a last chance handler 
that is capable of dealing with all exception conditions. This handler 
will abort execution of the diagnostic program by causing the program's 
cleanup code to be executed. 

In standalone mode, the VDS searches for a condition handler, and if none 
is found, a call to the last chance handler is forced. This call to the last 
chcince handler cannot be disabled by a diagnostic program. 

Additionally, the address of the VDS last chance handler is placed on the 
highest call frame of the VDS. This means that in user mode, the VDS last 
chance handler will take precedence over the VMS last chance handler. It 
also means that a diagnostic program cannot disable the VDS handler. 

If a diagnostic program declares a handler in one of its call frames, that 
handler will take precedence over the VDS last chance handler. In both 
user mode and standalone mode, a condition handler may be specified by 
loading the handler's address into the first address of the call frame (the 
address pointed to by the FP). In MACRO-32, this would be accomplished 
with the instruction: 

MOVAB CONDHNDLR,(FP) 

To declare a condition handler in BLISS-32, refer to the BLISS Language 
Guide. In user mode, diagnostic programs may also declare condition 
handlers by using the VMS $SETEXP system service. Refer to the VAX/VMS 
System Services Reference Manud. 

When a condition handler is given control, it is passed two cirguments. 
The first argument is the address of a signal array and the second is the 
address of a mechanism array. These arguments are passed in the manner 
indicated by Figure 4-5. 

Figure 4-5 Argument List Passed to a Condition Handler 



ADDRESS OF SIGNAL ARRAY 



ADDRESS OF MECHANIS^fl ARRAY 



-AP 



ZK-4787-85 
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The signal array indicates the type of condition. Its format is shown in 
Figure 4-6, where N is the total number of longwords (excluding the one 
containing N) making up the array. Condition names are defined by the 
$SSDEF macro (defined in STARLET.MLB listed in the VAX/VMS System 
Services Reference Manual) and by the $DS_DSDEF VDS macro. If the 
condition name parameter is DS$_UNEXPINT, the next argument is the 
SCB vector offset. 

Figure 4-6 Format of Signal Array 



CONDITION NAME 



OTO 2 EXCEPTION-SPECIFIC 
PARAMETERS 



EXCEPTION PC 



EXCEPTION PSL 



2K4788-86 



The mechanism array is illustrated in Figure 4-7. 
Figure 4-7 Format of Mechanism Array 



HANDLER ESTABLISHER FRAME FP 



FRAME DEPTH 



RO 



R1 



ZK-4789-85 



A condition handler can either field the condition or return with a resignal 
status to indicate that another handler should be called. If the handler 
fields the condition, it must place the status code SS$_CONTINUE in 
RO before returning. If the handler does not field the condition, the 
SS$_RESIGNAL status code must be placed in RO. Condition handlers 
end with the MACRO-32 instruction RET. A condition handler may use 
the $UNWIND macro to unwind the call frame (alter program flow) if it 
cannot handle the condition. Unwinding is detailed in the discussion of 
the $UNWIND macro in Chapter 5. 

The condition handler will receive control when any exception condition 
occurs. The handler must determine the type of exception (by examining 
the signal array) and decide whether or not to handle the particular 
condition. It is quite common to write a condition handler that will only 
process one or two types of exception conditions, and resignal all others 
so that another handler (such as the VDS last chance handler) can process 
them. 
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As an alternate method in standalone mode, the programmer may use the 
VDS macro $DS_SETVEC to store the address of a condition handler in 
the system control block (SCB). This allows the diagnostic program to field 
specific exception conditions, instead of all of them. By using this method, 
the VDS handler dispatcher is bypassed and control passes directly to the 
handler pointed to by the exception vector. This handler must process the 
exception and cannot resignal. 

If the diagnostic program contains a condition handler, the $DS_PRINTSIG 
macro can by used to automatically format and print the contents of the 
signal array. 

Note: For additional information regarding condition handling, refer to the VAX 
Architecture Handbook and the VAX/VMS Software Handbook. 



4.4.6 Handling Control-Cs 



Normally, when the user t)^es a control-C, program control passes to a 
VDS routine which aborts the current VDS function (such as executing 
a diagnostic program or building a p-table). It is possible to specify an 
alternate control-C handling mechanism within the diagnostic program 
by using the $DS_CNTRLC macro. The diagnostic program can use this 
macro to specify the address of a routine that is to be executed when a 
control-C is typed. 

When a control-C is typed, the VDS will pass program control to the 
specified routine. This routine will perform any necessary processing and: 

a. Pass a return status code of zero (in RO), which will cause the VDS to 
execute its own control-C handler. This technique is useful in cases 
where it is desirable for the diagnostic program to perform some 
processing of its own whenever a control-C is typed before the VDS 
takes control. 

b. Pass a nonzero status code (in RO), to indicate that the VDS should 
not execute its own control-C handler. In such a case, the VDS 
will continue performing the function it was performing before the 
control-C was typed. 

C. Not return at all. 

A possible use of options b and c would be the case where a special 
command language has been defined by the programmer (see 
Section 4.2.2.2, Prompting the User). In this case, it might be desirable 
for the user to be brought back to the special command line interpreter 
when a controI-C is typed. One of the special commands might have the 
same function as the VDS CONTINUE command (such as the RESUME 
used above), in which case option b would be used. If the RESUME 
command was not typed, the current function would be aborted and a new 
command would be fetched from the user, so option c would be selected. 

The $DS_CNTRLC macro also allows the programmer to disable control-C 
servicing. This makes it possible to ensure that certain portions of code will 
be executed without interruption, if necessary. Control-C servicing can be 
disabled temporarily while this uninterruptable code is executing, and then 
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reenabled. If a control-C is typed while control-C servicing is disabled, the 
control-C is not lost. It will be serviced when the servicing is reenabled. 
It is important to note that Control-C servicing must not be disabled for longer 
than 3 seconds at one time. Some run-time environments (APT in particular) 
cannot tolerate a longer control-C response delay, nor do users appreciate 
long periods of time when control-Cs are not serviced. Because dispatching 
to the control-C handler is performed by the VDS, a control-C will not be 
acknowledged while the diagnostic program is executing. Whenever the 
diagnostic program calls a system service routine, the service routine will 
check to see if a control-C has been typed. Suppose that by some chance 
the program contains a large segment of code that does not call any system 
service routines for a long period of time. If a control-C is t3^ed, it will 
not be acknowledged while this code is executing. In order to prevent this 
problem, any large section of code (or small section that loops for a long 
period of time) that does not call any system services must occasionally 
issue the $DS_BREAK macro. This macro will call a service that simply 
checks for a control-C and, if none has been received, merely returns. A 
$DS_BREAK macro or some other system service must be issued at least every three 
seconds. This is especially important in multiprocessor diagnostic programs 
(see Section 4.6.10). 

4.5 FILE MANAGEMENT 



4.5.1 Introduction 



It may be necessary for a diagnostic program to make reference to a 
separate, subsidiary file. In such a case, two facilities are available: 

• The $DS_LOAD system service 

• Record management services (RMS) 

The $DS_LOAD system service is useful for loading an entire file into a 
buffer area of memory. 

If more complex manipulations of a file are desired, such as referencing 
specific records or blocks, the record management services should be used. 

Level 2R (user mode) programs may use VAX-11 record management 
services (RMS) to manipulate files. The entire range of RMS services is 
available to the diagnostic program. Detailed information for VAX-11 RMS 
is available in the VAX-11 Record Management Services Reference Manual. 

Level 3 (standalone mode) programs are provided with a subset of the 
VAX-11 RMS functionality. This functionality resides within the VDS. It 
emulates VAX-11 RMS and is referred to in this manual as VDS RMS. 
For those functions supported by VDS RMS, the program interface is 
exactly the same as that of VAX-11 RMS; that is, both level 2R and level 
3 programs will use the same macros. In user mode the service calls are 
fielded by VMS, while in standalone mode they are handled by the VDS. 

Table 4-2 lists the limitations of VDS RMS, as compared to VAX-11 RMS. 
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Table 4-2 Comparison of VAX-1 1 RMS and VDS RMS 
VAX-11 RMS VDS RMS 



Provides read and write access. • Provides read access only. 

Supports sequential and • Supports sequential files only. 

relative files. • Supports sequential and random-by-RFA 

Supports sequential, random, file access. 

and random-by-RFA file access. ■ Terminals cannot be accessed. 

Terminals can be accessed. • Console device can be referenced 

Console device cannot be (RT-11 format only). 

referenced. • Only FAB, RAB, and FHC fields of XAB 

FAB, RAB, XAB, and NAM are defined. 

control structures are defined. 



Also, many of the option bits defined in the VAX-11 RMS control structures 
are not defined in VDS RMS. 

When using RMS in a level 2R program, use the VAX-11 Record Management 
Services Reference Manual as a reference guide. When using RMS in a level 
3 program, use this manual as the main reference guide and the VAX-11 
Record Management Services Reference Manual for additional information. 

The RMS macros are defined in STARLET.MLB for MACRO-32 and 
STARLET,L32 for BLISS-32. Note that these are VMS libraries and 
therefore contain the VAX-11 RMS macro definitions. This means that 
inclusion of unsupported RMS functions in a level 3 program will not be 
detected until the program is actually executed. For a diagnostic program 
to use RMS services on a file, the device on which the file resides must 
have been previously attached. (This is true for both level 2R and level 3 
programs.) If the device is the one from which the VDS was loaded, the 
VDS will automatically build a p-table for the device. If the device is not 
the VDS load device, the user can run the autosizer or manually attach the 
device. 



4.5.2 VDS RMS Overview 

VDS RMS provides facilities for easily gairung access to and reading 
sequential files on a disk or magnetic tape device, including the system's 
console device. The records within a file may be accessed sequentially, or 
they may be accessed randomly by a record's file address (RFA), discussed 
later. 

VDS RMS consists of a set of routines that will service requests for reading 
files, and a group of control structures that are used to pass information 
about the file between the diagnostic program and the VDS. VDS RMS 
supports three control struchires: the file access block (FAB), an extended 
attribute block p(AB), and the record access block (RAB). When a program 
requests a file service, fields within these control struchires will typically 
need to be loaded. The control structures contain information such as the 
name and type of file to be read, along with codes indicating how the fUe 
is to be referenced. 
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4.5.3 The FAB, RAB, and XAB 



The file access block (FAB) is a user control block that describes a 
particular file, a FAB is allocated by using the $FAB macro. One FAB 
must be defined for each file that is to be referenced. 

The record access block (RAB) contains information about the file's 
records. There must be a RAB associated with each FAB. An RAB is 
allocated by using the $RAB macro. 

An extended attribute block (XAB) is an optional control block that 
contains file attributes beyond those contained in a file's FAB. While 
VAX-11 RMS supports several different types of XABs, VDS RMS supports 
only the file header characteristics XAB (FHC XAB). The FHC XAB is 
allocated with the $XABFHC macro. 



4.5.4 Accessing the VDS RMS Control Structures 



The various fields of the FAB, RAB, and XAB can be initialized at program 
assembly time by using the predefined keywords that exist for each field. 
The fields can also be loaded at run time. The fields defined for each 
control block are named and described in the descriptions of the $FAB 
$RAB, and $XABFHC macros in Chapter 5. 

VDS RMS control structure fields are defined by a mnemonic of the general 
format: 

structure$datatype_name 

where structure is FAB, RAB, or XAB; datatype is a data type specifier (see 
Table 6-1); and name is the field name. Examples are: FAB$L_FNA and 
RAB$V_BIO. 

To access a structure field at run time, use the field name as an offset 
from the beginning of the struchire. For example, suppose an FAB has 
been defined with the $FAB macro and has been labeled FAB_BLOCK. 
Accessing fields of the FAB in a MACRO-32 program can be done with 
instuctions such as: 

MOVAB FILE_NAME, FAB BLOCK+FAB$L_FNA ;Load filename addr. 
or MOVE R0,FAB_BLOCK+FABSB_FNS ; Load filename size. 

In BLISS-32, the same fields would be referenced with the statements: 

FAB_ BLOCK [FAB$L_FNA] = FILE_NAME; !Load filename addr. 
FAB_ BLOCK [FAB$B_FNSJ = .FILE_NAME_SIZE; ! Load filename size. 

Offsets have been defined for some fields. Mnemonics are defined for 
both the bit offsets and the mask values of these offsets. For example, the 
mnemonics FAB$V_BIO and FAB$M_BIO are defined for the bit offset and 
the mask value of BIO parameter in the FAC field of the FAB. Referencing 
this bit at run time in MACRO-32 could be accomplished with the following 
(unrelated) instructions. 

BISB #FAB$M_BIO,FAB_BLOCK+FAB$B_FAC ;Load filename addr. 
or BBC #FAB$V_BIO,FAB_BLOCK+FAB$B_FAC [Branch if BIO clear. 
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Similar BLISS-32 statements would be: 

FAB_BLOCK [FAB$B_FAC] = .FAB_BLOCK [FAB$B_FAC] OR FAB$M_BIO; 
IF .FAB_BLOCK [FAB$B_FAC] <FAB$V_BIO, 1> THEN ... ; 

When a control block is declared (with the $FAB, $RAB, or $XABFHC 
macro), relevant fields may be initialized at compile time by using keyword 
representations of the fields. An example (in MACRO-32) is: 

$FAB FAC = <BIO,GET>,- 

FOP = RWO,- 
XAB = FHCXAB 

Similarly, fields can be loaded at run time with the $FAB_STORE or 
$RAB_STORE macro in MACRO-32 or with $FAB_1NIT or $RAB_INIT in 
BLISS-32. This example shows how to use the $RAB_IN1T macro. 

$RAB_INIT (BKT - 10, 

FAB = FAB_BLOCK 

RAG = SEQ, 

FNA = .FILE_NAME [ADDRESS], 

FNS = .FILE_NAME [SIZE]); 



4.5.5 Reading Files 



Two methods are available for reading files. These methods are record 
processing and block processing. When a file is being referenced, the 
programmer may use whichever method is more appropriate to the file 
and operations being performed. It is also possible to combine the two 
methods. 



4.5.6 Record Processing 

When using record processing, reading a file involves accessing records 
within the file. The number, size, and contents of a file's records are 
immaterial to RMS and are determined by whatever utility created the file. 

Two access methods are available for referencing records. The record 
access method is specified by loading the record access (RAC) field in the 
RAB. When specifying the RAC field, one of the following values may be 
chosen. 

• SEQ — sequential access 

Records retrieved through sequential access are returned in the order 
in which they were stored. Once all the records have been retrieved, 
any further attempt to sequentially access records in the file will cause 
an end-of-file condition to be returned. 

• RFA — record's file address access 

When a record is read from a file, an internal representation of the 
record's location within the file is returned in the RFA field of the RAB. 
VDS RMS can save the value contained in the RFA field and can use it 
to again retrieve that record by using a random-by-RFA request. 

Note: In VDS RMS, random-by-RFA access is supported for both disks and 
magnetic tapes. 
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Before the records of a file can be read, a record stream to the file must 
be established. A record stream is the association of a RAB to a FAB. 
After the file has been opened with the $OPEN macro, the record stream 
is established by placing the address of the FAB into the FAB field of the 
RAB. Then a $CONNECT macro is issued. 

Once the record stream has been established, records in the file can be 
read using the $GET macro. The first $GET will cause the file's first record 
to be read, and each successive $GET will fetch the next record if the 
RAB's RAC field is set to SEQ. If the RAC field is set to RFA, then each 
$GET will retrieve the record whose record file address (RFA) is stored in 
the RAB's RFA field. 

To break the record stream after record processing has been completed, 
a $DISCONNECT macro is issued. The $CLOSE macro is then used to 
terminate processing of the file. 

Example 4-1 illustrates record processing of a file. 

Example 4-1 Record Processing with RMS 



This routine reads a sequential file into a buffer. 



. PSECT 
BUFFER; .BLKB 
BUFF_DESC : 

.LONG 
.LONG 



MY_FAB: 
MY RAB: 



$FAB 
$RAB 



DATA,WRT,NOEXE 
1000 



BUFFER 

FNM = <INFILE:> 
FAB=MY_FAB,- 
UBF=BUFFER,- 
USZ=100 



Allocate a 1000-byte buffer 
Descriptor for buffer 
Length will be set at run time 
Address of buffer 

File access block 
Record access block 



.PSECT CODE, NOWRT, EXE 
.ENTRY SIMPLE, '^MO 

$OPEN FAB=MY_FAB 
BLBC ROjEXIT 
$CONNECT RAB=MY_RAB 
BLBC RO,EXIT 



GET_RECORD : 
$GET 
BLBC 
ADDL 

BRB 



RAB-MY_RAB ; 
RO , CHECK_DONE 
MY_RAB+$W_RSZ , - ; 
MY_RAB+RAi $ L_BUF 
GET RECORD ; 



CHECK_DONE: 

CMPL RO , #RMS$_EOF 
BNEQ ERRORS 
$CLOSE FAB=MY_FAB 
RET 



ERRORS : 



Open the file. 

Exit on error. 

Connect for record operations. 

Exit on error. 



Get a record 
Branch on error. 
Advance buffer pointer 

Get another record 



Done? 

No — error. 

Close the file. 

Return. 



(Error handler.) 
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4.5.7 Block Processing 



Block processing makes it possible to directly read the blocks of a file, 
ignoring the record structure that exists for the file. 

To indicate that block I/O will be performed on a file, the BIO bit in the 
FAC field of the FAB must be set before issuing the $OPEN macro. To 
perform block processing, the file must first be opened with the $OPEN 
macro. Then a RAB must be associated with the file's FAB by using 
the $CONNECT macro. Blocks can then be read from the file using the 
$READ macro. The first $READ will cause the first block of the file to be 
read. Each subsequent $READ will fetch the next sequential block of the 
file. 

When file processing has been completed, issue the $DISCONNECT 
macro followed by the $CLOSE macro. 



4.5.8 Mixing Block Processing and Record Processing 



If the BRO bit in the FAC field of the FAB is set, both block processing and 
record processing may be performed on the file. The BRO bit cannot be 
set after the $OPEN macro has been issued. 

It is possible to initially allow both block processing and record processing, 
then at some later time to disable record processing and allow only block 
processing. This is accomplished by setting the BIO bit in the ROP field of 
the RAB {not the BIO bit in the FAC field of the FAB). Once this bit is set, 
no further record processing will be allowed. 

Mixing processing modes requires some caution. For example, when 
switching from block reads to record reads on a disk, RMS's next record 
pointer and its next block pointer are both undefined, so the first $GET 
after a $READ and the first SREAD after a $GET must both use random-by- 
RFA access. For magnetic tape devices, the pointers will indicate the next 
block of the tape. 



4.6 VDS in a IVIultiprocessor Environment 



This section describes the VDS features that facilitate the execution of 
diagnostic programs in a multiprocessor environment (one VAX system 
with more than one processor, not a VAXCluster). 

Note: The discussions that follow do not refer to the environment established 
with the BOOT N command. BOOT N is used in a multiprocessor 
environment for uniprocessor operations only, whereas the services 
discussed in these sections refer to multiprocessor operations. Refer to 
the VAX/DS Diagnostic Supervisor User's Guide for a detailed dbcussion on 
the BOOT N command. 
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4.6.1 General Concepts 



In a multiprocessor environment the processor used to boot the VDS is 
called the primary processor (Pp). Each additional processor is called 
an attached processor (Ap). (Attached processors are not related to the 
VDS ATTACH command.) Processors labeled as primary and attached 
are software definitions and do not imply any particular hardware 
configuration. Refer to Chapter 2 of the VAX/DS Diagnostic Supervisor 
User's Guide for booting procedures on multiprocessor systems. 

When the VDS is booted, it always assumes there is only one processor, 
and there will always be only one copy of the VDS software. Control 
portions of the VDS, such as the command line interpreter and the 
command dispatcher, are executed only by the primary processor. Some 
portions of the code, such as system services and exception handlers, may 
be executed by any processor. 

It is assumed that a common memory is shared by all processors. 

Diagnostic programs are loaded by and initially executed by the primary 
processor. A diagnostic program may consist of one or more secondary 
portions that can be executed by one or more attached processors. In this 
document, the code that will execute in the primary processor is referred 
to as the primary process; code which will execute in an attached processor 
is called an attached process. All multiprocessor diagnostic programs must 
execute in kernel mode. 

If a diagnostic program is going to test more than one processor, that 
is, test the attached processors, each processor must be described by a 
hardware parameter table (p-table). See Section 3.2 for more information 
regarding p-tables. 



4.6.2 Multiprocessing Macros 



The VDS provides the following system services specifically for use in 
multiprocessor environments: 

• $DS_BOOTATTACHED boots an attached processor, that is, the Ap 
exits the halt state and enters the idle state. Prior to the state transition, 
the attached processor's SCB and stacks are built and initialized by the 
primary processor. 

• $DS_STARTATTACHED causes an attached processor to exit the idle 
state and enter the running state. The Ap will begin executing at the 
address specified. This code (the attached process) must be delimited 
by the $DS_BGNATTACHED and $DS_END ATTACHED macros. 
When execution of this code is complete, the processor is returned to 
the idle state. 

• $DS_HALTATT ACHED halts an attached processor, that is, the Ap 
exits the idle state and enters the halt state. An Ap must be in the idle 
state in order to be halted. 
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• $DS_SHOWIDLE indicates which attached processors are currently in 
the idle state. 

• $DS_EXIT is used to unconditionally branch to the end of the current 
program segment. When the ATTACHED argument is used, the 
branch destination is the $DS_END ATTACHED macro (the call 

to $DS_EXIT must be between the $DS_BGNATTACHED and 
$DS_ENDATTACHED macros). 

See Figure 4-8. 



4.6.3 Executing in an Attachied Processor 

In order for a diagnostic program to execute an attached process, the 
following steps must occur: 

1 The attached processor must be booted using the 
$DS_BOOT ATT ACHED service. 

2 The attached process must be loaded either by including the code 
within the source file of the code executing in the primary process or 
by including it in a separate file. If you use a separate file, you must: 

• Call the $DS_GETBUF service to allocate memory space for the 
attached process 

• Use the $DS_LOAD service or RMS services to load the file into 
the space assigned by the $DS_GETBUF service 

3 The $DS_STARTATTACHED service will pass the address of the 
attached process to the attached processor. If the attached process has 
been loaded into a buffer, the address is the same as the buffer itself. 

4 The attached processor will begin execution; VDS system services may 
be called. 

You must repeat the process for each attached processor. 
Figure 4-8 State Diagram for an Attaclied Processor 




MR-2280-RA 



The following table describes the conditions under which state transitions 
will occur for a given attached processor. Any other state transitions are 
imdefined within the VDS. 
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Table 4-3 State Transitions for an Attached Processor 

PREVIOUS CURRENT 

STATE STATE CONDITION 



HALT IDLE The Pp executed the $DS_BOOTATTACHED 

macro. 

IDLE MALT The Pp executed the $DS_HALTATTACHED 

macro. 

'OLE RUNNING The Pp executed the $DS_STARTATTACHED 

macro, or the Pp completed handling an 
exception, CNTRL-C or breakpoint (see 
Section 4.6.8) 

RUNNING IDLE The Ap executed the $DS_ENDATTACHED 

macro, i.e., completed the attached process, or 
while executing the $DS_BREAK macro, it was 
noted that an exception, CNTRL-C or breakpoint 
occurred, and therefore the attached process was 
preempted. 



4.6.4 Using VDS System Services 



Most system services may be called from attached processes. These 
services provide an interlocking mechanism, transparent to the diagnostic 
program, that ensures that only one processor will execute the service 
routine at a time. If two or more processors often issue calls to the same 
service, a large amount of system time may be spent waiting for one 
processor to finish with the service so that the other one can use it. Also, 
there is no way to determine which process will be serviced next; the order 
is completely arbitrary. The next processor to execute the service will be 
the first one to reference the interlocking flag after the service is released 
(by the previous processor). It is assumed (but not guaranteed by the 
software) that all requests will eventually be serviced. 

The following services may not be called from an attached process: 
$DS_CHANNEL 



$DS_SETMAP 
$DS_LOAD 
$DS_PARSE 
$DS_MMON 
$DS^MMOFF 
$DS_PRINTx 
$DS_ERRxxxx 
$DS_ASKxxxx 
$DS_SETVEC 
$DS_CLRVEC 
$DS_INITSCB 
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$DS_WAITMS 

$DS_SETIMR 

$DS_HIBER 

$DS_WAKE 

Additionally, the $DS_MMON and $DS_MMOFF services may not be 
called from the primary process after it has booted any attached processors 
($DS_BOOT ATTACHED) . 



4.6.5 Memory Management 

Memory mapping for all processors is identical. Any code within the VDS 
that alters the page tables alters the tables for each processor because there 
is one set of page tables for all processors. Page table base registers for 
each processor simply point to the same address. 

However, consider the foUoAving scenario: 

1 A diagnostic program that creates attached processes runs. 

2 Execution of the diagnostic program is stopped by control-C, a 
breakpoint, or an exception condition. 

3 A SET MM ON or SET MM OFF command is issued and then the 
CONTINUE command is issued. 

In this scenario, the state of memory memagement in the primary processor 
will change when the SET MM command is issued. The state of memory 
management in the attached processors, however, will not change until the 
CONTINUE command is issued. 

If each processor executes the $DS_GETBUF macro, $DS_RELBUF 
cannot be used to separately release buffers allocated to each processor. 
$DS_RELBUF deallocates the last allocated blocks regardless of which 
process requested them. Therefore, all $DS_GETBUF and $DS_RELBUF 
calls should be made by the primary process. Alternately, a globally- 
referenced location can be used to track total buffer allocation. One 
$DS_RELBUF call can then be issued to deallocate all allocated space at 
once. 



4.6.6 Timing 



The primary processor may call the $DS_WAITUS, $DS_WAITMS, and 
$DS_SETIMR services to establish timers. Attached processes may 
only call the $DS_WAITUS service. It is important to note that only one 
$DS_WAITUS request may be serviced at any time. If a process requests 
the $DS_WAITUS service but the service routine is already in use by 
another process, the requesting process is forced (by the VDS) to Wtiit until 
the service routine has completed its execution for the first process. The 
result will be that the actual amount of time the second process has to wait 
could be considerably longer than the actual wait time requested. 
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Be aware that if more than one process is waiting for service, it is arbitrary 
as to which is serviced first, as there is no enqueueing of requests. It 
is assumed (but not guaranteed by the software) that all requests will 
eventually be serviced. 



4.6.7 Input/Output 



4.6.8 Events 



Only the primary processor may receive I/O device interrupts. (For some 
processor types, this is a hardware restriction, for others, it is not. For 
consistency's sake, VDS implementation is the same for all processor 
types.) 

The $DS_CHANNEL service may be called only by the primary processor. 

Device interrupt service routines only execute in the primary processor and 
are considered a part of the main program. The main program may notify 
an attached process that an interrupt has been received by setting an event 
flag or by delivering an interprocessor interrupt to the attached processor. 

It is important to remember that the $DS_CHANNEL service only allows 
one device interrupt service routine in use at a time. Therefore, if several 
devices are to be active at once, they must all be serviced by the same 
interrupt service routine. (The routine can determine which device caused 
the most recent interrupt, since the vector address is passed to the routine.) 



4.6.8.1 The SCB 

Each processor has its own SCB that is initialized when the processor is 
bootstrapped. All SCBs are initialized as follows: 

• All vectors in the first half page of the SCB point to the proper 
exception handlers. Note that all handlers are the same for each 
processor. 

• The rest of the SCB (the device interrupt vector area) points to the 
VDS's unexpected interrupt handler. Only the primary processor, 
however, receives device interrupts (See Section 4.6.7, Input/Output). 

The $DS_SETVEC, $DS_CLRVEC, and $DS_INITSCB services can only 
be called by the primary process. If an attached process wants to modify 
its SCB, it must do so directly. The SCB base address is rehirned by the 
$DS_BOOTATTACHED service. 



4.6.8.2 Exceptions and Unexpected Interrupts 

The SCB of each processor is initialized so that exceptions vector into VDS 
condition handlers that provide interlocking. The last chance handler stops 
program execution on all processors, no matter which processor trapped 
out. The primary processor reenters VDS CLI and issues the DS > prompt. 
All attached processors reenter the idle state. 

Diagnostic programs can override the VDS last chance handler by 
specifpng their own condition handlers, as described in Section 4.4.5, 
Condition Handling. 
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Unexpected device interrupts are fielded by the primary processor (see 
Section 4.6.7). The primary processor's unexpected interrupt handler 
reports the interrupt to the user and reenters VDS CLI, issuing the DS> 
prompt. All attached processors are forced to reenter the idle state. 



4.6.8.3 Interprocessor Interrupts 

Diagnostic programs may implement interprocessor communication by 
using interprocessor interrupts. In order to make use of interprocessor 
interrupts, the SCBs of the various processors must be modified so that the 
IP interrupt vector points to an interrupt service routine specified by the 
program. 

The VDS does not use interprocessor interrupts except during execution of 
the $DS_HALTATTACHED service on VAX 88XX processors. 



4.6.8.4 ASTs 

Only the primary processor can execute a service that provides AST 
delivery. These services, for level 3 programs, include $SETIMR, 
$DS_CNTRLC, and indirectly, $DS_WAITMS. 



4.6.8.5 Control-Cs 

You can return to the VDS CLI and the DS> prompt by tjrping control-C. 
Attached processors return to the idle state the next time they call the 
$DS_BREAK service (see Section 4.4.6) 

As is currently the case, a diagnostic program may declare its own 
control-C handler to take precedence over the VDS control-C handler. 



4.6.8.6 Breakpoints 

Breakpoints can be set in attached processors. When a breakpoint is 
executed by any processor, all processors in the running state exit that state 
and enter the idle state (except for the primary processor, which enters 
VDS command mode). Typing the CONTINUE command will cause all 
processors to exit the idle state and return to the running state at the PC 
from which they were preempted. T3rping the NEXT command will cause 
execution of the next instruction only if the breakpoint was executed by the 
primary processor. This means that single stepping through code can only 
occur in the primary process. However, breakpoints can be executed by 
any processor. 

Note: One or more breakpoints can be set in any one of the the processors 

(primary or attached). However, breakpoints cannot be set in more than 
one processor at a time, or unpredictable results will occur. 

After a breakpoint has been executed, the general purpose registers (GPRs) 
of the processor that executed the breakpoint can be examined. The GPRs 
of the primary processor can always be examined; however, the GPRs 
of any other attached processors will be inaccessible. (Commands for 
examining registers are described in the VAX/DS Diagnostic Supervisor User's 
Guide.) 
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4.6.9 Communication Between the Primary and Attached Processes 

The VDS does not provide services specifically for communication between 
the primary process and the attached processes. However, the following 
techniques and services can be used to design a scheme which will 
facilitate necessary sycnchronization. 

• Event Flags — Useful for passing status information between the 
primary and various attached processes. The $SETEF, $CLREF, 
$READEF, $WAITFR, $WFLAND, and $WFLOR services can be used 
by any process. 

• Interprocessor Interrupts — Available for use by the diagnostic 
program. See Section 4.6.8.3 and the VAX Architecture Standard 
(SRM) for implementation specifics. 

• Common mailbox — A common data area can be specified in which to 
pass information between the main process and the attached processes. 

• Dispatch vectors — Attached processes can call routines in the main 
process via dispatch vectors, stored in a table in the main process, that 
point to the routines. If these vectors are assigned absolute addresses, 
attached processes not linked with the main process can reference 
them. (If the code for attached processes is linked with the main 
process, dispatch vectors are unnecessary, since addressing references 
may be relative and can be resolved at link time.) 



4.6.10 Restrictions 



The following restrictions apply to diagnostic programs using the 
multiprocessing features of the VDS: 

• As with single processor systems, code executing in attached 

processors must periodically call the $DS_BREAK service. 17118 rule 
is very important, as breakpoints, control-C's, and exception handling 
depend upon this rule being followed. 

One simple method to ensure that all processors are periodically 
issuing $DS_BREAK calls is to use the following scheme. The following 
scheme, as shown in Table 4-4, is not sufficient if there are any sections 
of code which loop but do not include calls to the $DS_BREAK 
service. 
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Table 4-4 Algorithm for Demonstrating Use of $DS_BREAK 

Primary Processor Code Attached Processor Code 

Continue_attached = FALSE; $DS_BGNATTACHED 

Attached_not_done = TRUE; FOR N = 1 to maxtests DO 

$DS_STARTATTACHED; > BEGIN 

WHILE Attached_not_done DO Execute test(N); 

$DS_BREAK; $DS_BREAK; 

END; 
Attached_not_done = FALSE; 
REPEAT 
$DS_BREAK 
IF errors THEN report errors. UNTIL Continue_attached; 



Attached_not_done = TRUE; 

Continue_attached = TRUE; Continue. 



Continue. $END_ATTACHED; 



With the exception of $DS_BGNATTACHED and 
$DS_END ATTACHED, code executing in attached processors may 
not use any of the program structure macros. (These macros include 
$DS_BGNTEST, $DS_ENDTEST, $DS_BGNSUB, $DS_ENDSUB, and 
the macros $DS_HEADER and SDS.DISPATCH that define such data 
structures as the diagnostic header and the dispatch table, respectively.) 
All initialization and clean-up code, looping, and error reporting must 
be contained within code executed by the primary processor. 

The load image for a diagnostic program may not be larger than 
approximately 63.5 kilobytes. If the total size of the code to be 
executed by the primary and all attached processes exceeds the 
maximum, you have to store the code for attached processors in 
separate loadable images. (Refer to Section 4.6.3, Bcecuting in an 
Attached Processor.) 

As stated previously, requests for system services are not enqueued. 
Therefore, if several attached processes are simultaneously requesting 
the same service, there is no way to determine which process will 
be serviced next. It is assumed (but not guaranteed by the software) 
that all requests will eventually be serviced. All services have an 
interlocking mechanism, so that the next processor to execute the 
service is the first one to reference the interlocking flag after the service 
is released (by the previous processor.) 

As discussed in Section 4.6.7, Input/Output, only the primary processor 
can receive I/O device interrupts. 

Use the standard methods for declaring condition handlers, as 
described in this guide as well as in the VMS documentation. 
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Code executing in an attached processor may not call the following 
services: 

$DS_ CHANNEL 

$DS_SETMAP 

$DS_LOAD 

$DS_PARSE 

$DS_MMON 

$DS_MMOFF 

$DS_PRINTx 

$DS_ERRxxxx 

$DS_ASKxxxx 

SDS^SETVEC 

$DS_CLRVEC 

$DS_INITSCB 

$DS_WAITMS 

$DS_SETIMR 

$HIBER 

$WAKE 

All multiprocessor diagnostic programs must execute in kernel mode. 

It is recommended that the clean-up section call the 
$DS_HALTATTACHED service for each attached processor, so that 
each processor will be left in a known, static state. 

After an attached processor has been booted via the 
$DS_BOOTATTACHED service and after a breakpoint has been 
executed by that processor, the EXAMINE and DEPOSIT commands 
may be used to reference the processor's GPRs and IPRs. The new 
command, SET CPU, is used to select the processor to reference. The 
PC of an attached processor cannot be modified with the DEPOSIT 
command. Only the PSW portion of the PSL can be referenced. 
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5.1 Introduction 



This chapter describes in detail the format and function of each macro used 
in VDS diagnostic programs. The macros are listed alphabetically, ignoring 
the name's prefix. 



5.2 Coding System Service IVlacro Calls 



The VDS system services are invoked by issuing a macro call for the 
desired service and, if required, including an argument list to provide 
values for the macro's parameters. Before any system service macros can 
be called, the $DS_DSSDEF macro must be declared, which defines the 
system service entry points. 



5.2.1 Fieldsof the IVlacro Name 

Macro names consist of three fields. These fields are: 

• A prefix 

This prefix may be $DS_d or $. Macro names having the $DS_ prefix 
are defined exclusively for use with the VAX Diagnostic Supervisor. 
Macro names having the $ prefix are defined for use not only with the 
VAX Diagnostic Supervisor, but also for any program running under 
the VAX/VMS operating system. 

Diagnostic programmers should not assume that a macro name's prefix 
implies any restriction on the run-time environment in which the macro 
may be used. For instance, do not assume that macros with the $ prefix 
may only be used for level 2R programs. Any run-time environment 
restrictions that may exist for a particular macro will be noted in the 
description of the macro. 

• A name 

This name identifies the system service being invoked by the macro 
call. 
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• A suffix 

For MACRO-32 programs this suffix may be _S, _G, _L, or _DEF. 

The _S suffix indicates that the system service routine is to be called 
with a CALLS MACRO-32 instruction. If this suffix is used, the macro 
call must include an argument list to provide values for required 
parameters. (Specifying argument lists is detailed below.) Following is 
an example of the _S form of the macro call: 

SDS_ERRHRRD_S - 

UNIT .= LOG_UNIT, - 
MSGADR = HARD12_MSG, - 
PRLINK = HARD_MSGRTN, - 
PI = SAVED_STATUS 

If the _G suffix is used, the system service routine will be called with 
a CALLG MACRO-32 instruction. In this case, only one argument is 
specified with the macro call; the argument is the address of a list of 
arguments to the system service. Following is an example of the %%% 
_G form of the macro call; 

$DS_ERRHARD_G HARD_ARGLIST 

The _L suffix will not call the system service. It will generate an 
argument list. This argument list may later be passed to the system 
service when the service is called with a _G suffix, if the list's address 
is used as the macro call's argument. The following is an example of 
the _L form of the macro call: 

HARD_ARGLIST: 

$DS_ERRHARD_L UNIT = LOG_UNIT, - 

MSGADR = HARD12_MSG, - 
PRLINK = HARD_MSGRTN, - 
PI = SAVED_STATUS 

The _DEF suffix simply generates symbolic names for the service's 
parameters. These symbolic names can be used to fill in fields of an 
argument list that was defined with a _L macro. Names will consist of 
the service name, a $, an _, and the parameter name. The symbolic 
names should be used as offsets from the beginning of the argument 
list. The following is an example of the _DEF form of the macro call: 

$DS ERRHARD DEF 



MOVAL HARD13_MSG, HARD_ARGLIST+ERRHARD$_MSGADR 

For BLISS-32 programs, the suffix field of the macro call is always left 
blank. System services are always called with a CALLS MACRO-32 
instruction, and the macro call must include an argument list. 
(Specifying argument lists in BLISS-32 is decribed in the next section.) 
The following is an example of invoking a system service in BLISS-32. 

$DS_ERRHARD 

(UNIT = .LOG_UNIT, 
MSGADR = HARD12_MSG, 
PRLINK = HARD_MSGRTN, 
PI = . SAVED_STATUS ) ; 
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5.2.2 Macro Arguments 

Most system services possess a set of input parameters for which values 
must be provided when a service is invoked. Values are associated with 
input parameters via arguments to the service's macro call. 

For MACRO-32 programs, macro arguments may be specified in either of 
two ways: 

• Arguments may be specified as a list with each argument except the 
last one followed by a comma. The position of each argument is 
significant; thus, arguments must be listed in the order specified in 
the macro's description. If a particular argument is optional and is to 
be omitted, a comma must be included to signify its omission. An 
example of a macro call using positional specification of arguments is: 

SDS_GETBUF_S #3,,, #1 

• Arguments may be specified by kejnvords. Keywords are symbolic 
names that are assigned to input parameters. A keyword is defined for 
every parameter of every macro, and that keyword is the name used 
to identify the parameter in the description of the macro's MACRO-32 
format. For example, the $DS_GETBUF macro's MACRO-32 format is 
defined as: 

$DS_GETBUF_x pagcnt, [retadr], [phyadr], [region] 

(Brackets indicate optional arguments). Specifjnng this macro's 
arguments with keywords would appear as: 

$DS_GETBUF_S PAGCNT=#3, REGION=# 1 

Notice that when using keywords, it is not necessary to include commas 
for unspecified arguments. 

For BLISS-32 programs, macro arguments may also be specified 
positionally or by keyword, but the choice is not up to the programmer. 
For some macros, arguments must be specified with ke3Awords. For others, 
arguments must be specified positionally. If the description of the macro's 
BLISS-32 formatspecifies keywords (capital letters followed by an equal 
sign), the keyword must be used. If the description does not indicate 
keywords, positional specification is required. 



5.2.3 Use of RO and R1 



Many system services make use of RO and Rl. Never assume that these 
two registers retain the same values after a system service call as they 
had before the call. Unlike all other general purpose registers, which are 
preserved during system service calls and do not change, RO and Rl are 
not necessarily constant. 
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5.2.4 Return Status Codes 



All system services return an error status code in RO. This status code should 
always be examined immediately after the diagnostic program regains program 
control from the service. In addition to RO, some services return more status 
information in Rl. 

All status codes have symbolic names associated with them. Each of these 
names will have one of three possible prefixes. These prefixes are: 

• SS$_ — Most status codes begin with this prefix. For MACRO-32, these 
codes are defined by the $SSDEF macro. 

• RMS$_ — Status codes associated with Record Management Services 
(RMS) begin with this prefix. For MACRO-32, these codes are defined 
by the $RMSDEF macro. 

• DS$_ — A few status codes begin with this prefix. Such codes are 
defined for MACRO-32 by the $DS_DSDEF macro. 

For status codes whose symbolic names begin with SS$_ or RMS$_, the 
low-order three bits indicate the severity of the error. Severity codes are as 
follows: 



Value (Binary) 


Meaning 




Symbolic Name 


000 


Warning 




STS$K_WARNING 


001 


Success 




STS$K_SUCCESS 


010 


Error 




STS$K_ERROR 


oil 


Informational 




STS$K_INFO 


100 


Severe or fatal 


error 


STS$K_SEVERR 


101-111 


Reserved 







Symbolic names are defined by VMS with the $STSDEF macro. 

SS$_NORMAL versus DS$_NORMAL — Most services rehirn the normal 
status to indicate that the service was successfully completed. For some 
services, the correct prefix on the normal return code is SS$_; for other 
services, DS$_ is the proper prefix. These two status codes are not 
interchangable. Care must be taken that a program's code uses the proper 
normal status code for the particular service being invoked. Each service's 
macro description will indicate which code is correct. 

For all status codes that indicate an error condition, bit of RO will be 
cleared. For all other status codes, bit of RO will be set. Thus for 
MACRO-32 programs, it is possible to determine that an error has occurred 
by simply using the BLBS or BLBC instruction. However, this method is 
not recommended. Program readablility is improved if status codes are 
always tested by using symbolic names, as in the example: 

$QIO_G QIO_ARGLIST ; Enqueue I/O request. 
CMPL RO, #SS$_NORMAL ;If success, then continue. 
BNEQ QI0_ERR0R ;Else branch to the error handler. 

; Continue 
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5.3 Conventions Used in this Chapter 



In the macro descriptions that follow, certain conventions have been 
adhered to. These conventions are as follows: 

• For macros that accept arguments, those arguments that are optional 
have been indicated by enclosing the parameter name in brackets ([...1). 

• Macro parameters are listed in positional order; that is, if arguments 
are to be listed positionally, they must be listed in the order indicated 
in the macro format. 

• For MACRO-32, the parameter name indicates the keyword that must 
be used if arguments are to be specified with ke5rwords. 

• For BLISS-32, keywords are indicated in capital letters. If a keyword is 
not supplied in the macro format, the macro will not accept keyword 
arguments. In such a case, arguments must be specified positionally. 

• The description of each macro parameter will indicate whether the 
argument supplied for that parameter must be a value, an address, or a 
string. 

— Values as arguments. If a value is required, the argument will 
be interpreted as a value. Thus, if a literal is specified for the 
argument, that literal will be interpreted as being the argument. If 
an address is specified, the CONTENTS of that address will be 
interpreted as being the argument. 

— Addresses as arguments. If an address is required, the argument 
will be interpreted as an address. No translation of the argument 
occurs. 

— Strings as arguments. If a string is required, the argument will 
be interpreted as a literal string. For MACRO-32, strings must be 
enclosed in angle brackets (<...>). For BLISS-32, strings must be 
enclosed in single quotation marks ('...'), and if the string itself is to 
contain the (') character, it must be included twice, as in 'Debbie"s 
Program'. 

• Some services require that the address of a quadword descriptor or 
character string descriptor be passed. For our purposes, these terms 
are interchangeable and refer to a quadword that describes a string in 
the manner illustrated by Figure 5-1. 

Figure 5-1 Quadword String Descriptor 



31 16 15 



LENGTH OF STRING 



ADDRESS OF STRING 



ZK-479a85 
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String descriptors can be generated by using the .ASCID directive in 
MACRO-32, tt\e %ASCID directive in BLISS-32, or the $DS_STRING 
macro. 



5.4 System Service Descriptions 



The following pages describe, in detail, how to use the VAX/DS system 
services and macros. 
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$DS_ABORT 



The Abort Program or Test service can be used to stop execution of either 
the whole diagnostic program or just the current test. If the program is 
aborted, a system service is called. This service will execute the program's 
cleanup code and return control to the VDS command line interpreter. If 
only the current test is aborted, the test is exited with the l\/IACRO-32 
instruction, RET, and the next selected test is called. 



MACRO-32 



$DS_ABORT 

(No suffix.) 



arg 



BLISS-32 



$DS_ABORT (ARG = arg); 



ARGUMENTS ^rg 



PROGRAM or TEST. If PROGRAM is specified, then the program will be 
aborted. If TEST is specified, the current test will be exited (with an RET 
instruction), and the next selected test will be called. If no argument is 
specified, the program will be aborted. 



RETURN 
STATUS 



No status is returned, because $DS_ABORT TEST does not generate a 
service call and $DS_ABORT PROGRAM does not allow program control 
to return to the diagnostic program. 



MACRO-32 
EXAMPLE 

$DS_ABORT PROGE^M 

$DS_ABORT 

$DS ABORT TEST 



BLISS-32 
EXAMPLE 

$DS_ABORT (ARG=PROGRAM) ] 
$DS_ ABORT ( ) ; 
$DS_ABORT ( ARG=TEST ) ; 



5-7 



$DS_$ADD 



$DS_$ADD 



The $DS_$ADD p-table descriptor macro is used to add the contents of the 
value register (see Section 3.2.3.3) into a field of the p-table being built. 
The field is fetched, the addition is performed, and the result is placed 
back into the field. 



MACRO-32 



$DS_$ADD (offset, pos, size) 



BLISS-32 



$DS_$ADD (OFFSET = offset, POS = pos, SIZ = size); 



ARGUMENTS 



offset 

The byte offset into the p-table of the field to which the contents of the 
value register are to be added. 

pos 

Bit position of the field, relative to the beginning of the byte specified by 
"offset." If the field starts on a byte boundary, this value will be 0. 

size 

Number of bits making up the field. The size cannot be larger than 32. 



NOTES 



1 Bits added (or carried) beyond the field width are lost. 

2 The contents of the value register are not changed. 

3 Code generated by macro (shown in Macro-32; Bliss-32 is equivalent): 



.BYTE '^XSA 

.WORD offset 

. BYTE pos 

.BYTE size 



Beginning of ADD directive 
Word data structure offset 
Bit position in word 
Bit field size 



IVIACRO-32 
EXAMPLE 



$DS_$ADD OFFSET=HP$A_DEVICE, POS=0 , SIZE=32 
$DS_$ADD <^X40>, 0, 32 
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BLISS-32 
EXAMPLE 



$DS_$ADD (OFFSET=%FIELDEXPAND(HP$A_DEVICE,0) , 
POS=%FIELDEXPAND(HP$A_DEVICE, 1) , 
SIZE=%FIELDEXPAND(HP$A_DEVICE,2 ) ) ; 

$DS_$ADD (OFFSET=%X'40' , POS=0, SIZ=32); 
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$ASCTIM 



The Convert Binary Time to ASCII String system service converts the 
contents of a quadword from 64-bit time format into an ASCII string. This 
is the converse of the function performed by the $BINTIM service. 



MACRO-32 



$ASCTIIVI_x [timlen], timbuf, [timadr], [cvtfig] 



BLISS-32 



SASCTIM (rriMLEN = timlen], TIMBUF =timbuf, 
[TIMADR = timadr], [CVTFLG = cvtfig]); 



ARGUMENTS 



timlen 

Address of a word to receive length of output string. 

tImbuf 

Address of a character string descriptor (see Section 5.3) pointing to buffer 
to receive converted string. 

timadr 

Address of the 64-bit time value to be converted. A value of (the default) 
results in the current system time being converted. A positive value 
represents an absolute time. A negative value represents a relative time 
(offset from the current time). 

cvtfig 

Conversion indicator. A value of 1 causes only the hour, minute, second, 
and hundredth of second fields to be returned, while a value of causes 
the full date and time to be returned. 



RETURN 
STATUS 



SS$_NORMAL 
SS$_IVTIME 



Service successfully completed. 

The specified relative time is equal to or greater than 
10,000 days. 



NOTES 



The ASCII string returned by the service will be in the format specified 
in the notes to the SBINTIM service. 

To receive full absolute date and time, the "timbuf" buffer length must 
be 23 b3rtes. To receive the full relative day and time, the buffer length 
must be 16 bjrtes. Specifying a shorter buffer length will cause the 
returned string to be truncated to the buffer size. This may be useful 
if, for example, only the absolute date is required, and not the time. It 
is only necessary to provide a buffer that can hold the amount of the 
returned string the caller wishes to receive. 
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MACRO-32 
EXAMPLE 

$ASCTIM_S STR_LENGTH, BUFPTR, TIME, #1 



BLISS-32 
EXAMPLE 

$ASCTIM (TIMLEN=STR_LENGTH, TIMBUF=BUFPTR, TIMA.DR=TIME, CVTFLG=1); 
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$DS_ASKADR 



The $DS_ASKADR system service is used to obtain information from tiie 
program user at run time. With this service, the diagnostic program can 

• Prompt the user with a message specified by the programmer 

• Obtain l<eyboard input from the user 

• Interpret and validate the input string 

• Store the value specified by the input string 

The Ask for Address ($DS_ASKADR) system service is used when the 
information requested from the user is an address. 



MACRO-32 



$DS_ASKADR_x msgadr, datadr, [radix], [lolim], 

[hilim], [defalt], [unused], [exword] 



BLISS-32 



$DS_ASKADR (MSGADR = msgadr, 

DATADR = datadr, 
[RADIX = radix], 
[LOLIM = lolim], 
[HILIM = hilim], 
[DEFALT = defalt], 
[EXWORD = exword]); 



ARGUMENTS 



msgadr 

Address of counted ASCII string to be used as user prompting message. 

datadr 

Address of longword to receive interpreted user response value. 

radix 

Radix in which the user response is to be interpreted. Legal values for 
this parameter are defined by the macro $DS_PARDEF, and consist 
of PAR$_BIN, PAR$_OCT, PAR$_DEC, and PAR$_HEX. The default is 
hexadecimal. 

lolim 

Minimum acceptable value for numeric user reponse. The default is 
(unsigned) 0. 

hiiim 

Maximum acceptable value for numeric user response. The default is 
(unsigned) FFFFFFFF (hexadecimal). 
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defalt 

The value to be used if the user does not provide a response (user only 
types return key). The default value for "defalt" is 0. If no default is to be 
used, then NODEF must be set in the "exword" parameter. 

unused 

Reserved for expansion. 

exword 

The "exception mask." This is a longword containing "exception 
flags." These flags are used to modify the interpretations of some of 
the other parameters. Symbols for the exception flags are defined by 
the $DS_PARDEF macro. Refer to the description of that macro for the 
complete symbol names. The flags are: 

• NODEF — There is to be no default value for the user response. In 
other words, the "defalt" parameter is to be ignored. 

• ATDEF — The argument specified for the "defalt" parameter is the 
address of a location containing the default value. 

• ATLO — The argument specified for the "lolim" parameter is the 
address of a location containing the low limit value. 

• ATHI — The argument specified for the "hilim" parameter is the 
address of a location containing the high limit value. 

By default, all flags are cleared. 



RETURN 
STATUS 



SS$_NORMAL 
DS$_PROGERR 



Service successfully completed. 

An incorrect number of arguments was supplied witfi 
the macro. 



NOTES 



If the VDS control flag OPERATOR is clear and if no default value has 
been specified for the prompting message, the diagnostic program will 
be aborted. Thus, if the diagnostic program is intended to be executed 
in an automated run-time environment (such as APT), these macros 
cannot be used unless default values are provided. 

It is also required that if these macros are used in the DEFAULT 
program section (see Section 3.8.3), default values must be provided. 

If the VDS control flag PROMPT is set, the ranges and default values 
for user responses will be displayed along with the prompting message. 

To ensure that prompting messages are left-justified, precede each 
prompting message with a CR and LF. 

Figure 5-2 illustrates the format of the "valtab" table. 
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Figure 5-2 Valtab Table Format 



31 



8 7 



Unused 


N 




















• 
• 

• 
• 











.ASCIC strlngi 



*■ .ASCIC string2 



.ASCIC stringN 
ZK-4793« 



In a multiprocessing environment, $DS_ASKADR cannot be called 
from within a block of code delineated by the $DS_BGN ATT ACHED 
and $DS_ENDATTACHED macros. 



MACRO-32 
EXAMPLE 



PROMPT I 
RESPONSE: 



.ASCIC /DEVICE ADDRESS:/ 
.LONG 



$DS_ASKADR_S - 
MSGADR 
DATADR 
RADIX 
LOLIM 
HILIM 
DEFALT 



PROMPT, - 
RESPONSE, - 
#PAR$_OCT, 
#760000, - 
#777777, - 
#764000 
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BLISS-32 
EXAMPLE 



BIND 

PROMPT = UPLIT (%ASCIC 'IS THE DRIVE WRITE-ENABLED? ) ; 

LITERAL 

LOW_LIM = 760000, 
HI_LIM = 777777, 
DEFAULT = 764000; 



LOCAL 






RESPONSE; 






$DS ASKADR 


(MSGADR 


= PROMPT, 




DATADR 


= RESPONSE, 




RADIX 


= PAR$ OCT, 




LAIM 


= .LOW LIM, 




HILIM 


= .HI LIM, 




DEFALT 


= .DEFAULT) 
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$DS_ASKDATA 



The $DS_ASKDATA system service is used to obtain information from the 
program user at run time. With this service, the diagnostic program can 

• Prompt the user with a message specified by the programmer 

• Obtain keyboard input from the user 

• Interpret and validate the input string 

• Store the value specified by the input string 

The Ask for Data ($DS_ASKDATA) system service is used when the 
information requested from the user is a numeric value other than an 
address. 



MACRO-32 



$DS_ASKDATA_x msgadr, datadr, [radix], [mask], 

[lolim], [hilim], [defalt], [unused], 
[exword] 



BLISS-32 



$DS_ASKDATA (MSGADR = msgadr, 

DATADR = datadr, 
[RADIX = radix], 
[MASK = masi<], 
[LOLIM = lolim], 
[HILIM = hilim], 
[DEFALT = defalt], 
[EXWORD = exword]); 



ARGUMENTS 



msgadr 

Address of counted ASCII string to be used as user prompting message. 

datadr 

Address of longword to receive interpreted user response value. 
Value is placed in bit position indicated by "mask." 

radix 

Radbc in which the user response is to be interpreted. Legal values for 
this parameter are defined by the macro $DS_PARDEF, and consist of 
PAR$_BIN, PAR$_OCT, PAR$_DEC, and PAR$_HEX. The default radix is 
decimal. 
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mask 

Mask indicating the bit positions within "datadr" in which the interpreted 
user response should be stored. The default value is FFFFFFFF 
(hexadecimal), indicating 32 bits starting at bit 0. 

lolim 

Minimum acceptable value for numeric user reponse. Default is minus 2 to 
the 31st power. 

hilim 

Maximum acceptable value for numeric user response. Default is 2 to the 
31st power minus 1. 

defalt 

The value to be used if the user does not provide a response (user only 
types return key). The default value for "defalt" is 0. If no default is to be 
used, then NODEF must be set in the "exword" parameter. 

unused 

Reserved for expansion. 

exword 

The "exception mask." This is a longword containing "exception 
flags." These flags are used to modify the interpretations of some of 
the other parameters. Symbols for the exception flags are defined by 
the $DS_PARDEF macro. Refer to the description of that macro for the 
complete symbol names. The flags are: 

• NODEF — There is to be no default value for the user response. In 
other words, the "defalt" parameter is to be ignored. 

• ATDEF — The argument specified for the "defalt" parameter is the 
address of a location containing the default value. 

• ATLO — The argument specified for the "lolim" parameter is the 
address of a location containing the low limit value. 

• ATHI — The argument specified for the "hilim" parameter is the 
address of a location containing the high limit value. 

By default, all flags are cleared. 



RETURN 
STATUS 



SS$_NORMAL 
DS$_PROGERR 

DS$_TRUNCATE 



Service successfully completed. 

An incorrect number of arguments was supplied witli 
the macro. 

Ttie value specified by the user was too large to fit 
into the bit field specified by the caller. The value 
was truncated in order to fit into the specified field. 
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NOTES 



If the VDS control flag OPERATOR is clear and if no default value has 
been specified for the prompting message, the diagnostic program will 
be aborted. Thus, if the diagnostic program is intended to be executed 
in an automated run-time environment (such as APT), these macros 
cannot be used unless default values are provided. 

It is also required that if these macros are used in the DEFAULT 
program section (see Section 3.8.3), default values must be provided. 

If the VDS control flag PROMPT is set, the ranges and default values 
for user responses will be displayed along with the prompting message. 

To ensure that prompting messages are left-justified, precede each 
prompting message with a CR and LF. 

See Figure 5-2, Valtab Table Format, in the $DS_ASKADR macro 
section. 

In a multiprocessing environment, $DS_ASKDATA cannot be called 
from within a block of code delineated by the $DS_BGNATTACHED 
and $DS_ENDATTACHED macros. 



MACRO-32 
EXAMPLE 



PROMPT ! 
RESPONSE : 



.ASCIC /DEVICE ADDRESS;/ 
.LONG 



$DS_ASKDATA_S - 
MSGADR 
DATADR 
LOLIM 
HILIM 
DEFALT 



PROMPT, - 

RESPONSE, 

♦ 0, 

#12, 

#0 



BLISS-32 
EXAMPLE 



BIND 

PROMPT = UPLIT (%ASCIC 

LOCAL 

RESPONSE; 



IS THE DRIVE WRITE-ENABLED?) j 



SDS_ASKDATA (MSGADR 
DATADR 
LOLIM 
HILIM 
DEFALT 



= PROMPT, 

= RESPONSE, 

= 0, 

= 132, 

= DEFAULT_PAGE_WIDTH) 
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$DS_ASKLGCL 



The $DS_ASKLGCL system service is used to obtain information from the 
program user at run time. With these services, the diagnostic program can 

• Prompt the user with a message specified by the programmer 

• Obtain keyboard input from the user 

• Interpret and validate the input string 

• Store the value specified by the input string 

The Ask for Logical Response ($DS_ASKLGCL) system service is used 
to asl< the user a question that can be answered with a "yes" or "no" 
response. Optionally, the caller can specify addresses of routines that will 
automatically be branched to on a "yes" or "no" response. 



MACRO-32 



$DS_ASKLGCL_x msgadr, datadr, [pos], [yexfer], 

[noxfer], [defalt] 



BLISS-32 



$DS_ASKLGCL (MSGADR = msgadr, 

DATADR = datadr, 
[POS = pos], 
[YEXFER = yexfer], 
[NOXFER = noxfer], 
[DEFALT = defalt]); 



ARGUMENTS 



msgadr 

Address of counted ASCII string to be used as user prompting message. 

datadr 

Address of longword to receive interpreted user response value. 
Value will be placed in one bit, indicated by "pos." The bit can be 
compared with PAR$_NO and PAR$_YES, defined in $DS_PARDEF 
(No = 0, yes = 1). 

radix 

Radix in which the user response is to be interpreted. Legal values for 
this parameter are defined by the macro $DS_PARDEF, and consist of 
PAR$_BIN, PAR$_OCT, PAR$_DEC, and PAR$_HEX. The default radbc is 
decimal. 

pos 

Bit offset from "datadr," indicating where interpreted user response is to 
be stored. The legal range is through 7. Default is 0, indicating value 
should be stored starting at bit of "datadr." 
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lolim 

Minimuin acceptable value for numeric user reponse. Default is minus 2 to 
the 31st power. 

hilim 

Maximum acceptable value for numeric user response. Default is 2 to the 
31st power minus 1. 

defalt 

The value to be used if the user does not provide a response (user only 
types return key). The default value for "defalt" is 0, which is equivalent to 
a "no" response. If no default is to be used, then NODEF must be set in 
the "exword" parameter. 

For the $DS_ASKLGCL macro, default values may be specified by the 
symbols PAR$_NO and PAR$_YES, defined by the $DS_PARDEF macro. 

yexfer 

Address to branch to if user response is "yes." Default is 0, meaning no 
branch will take place. 

noxfer 

Address to branch to if user response is "no." Default is 0, meaning no 
branch will take place. 

unused 

Reserved for expansion. 

exword 

The "exception mask." This is a longword containing "exception 
flags." These flags are used to modify the interpretations of some of 
the other parameters. Symbols for the exception flags are defined by 
the $DS_PARDEF macro. Refer to the description of that macro for the 
complete symbol names. The flags are: 

• NODEF — There is to be no default value for the user response. In 
other words, the "defalt" parameter is to be ignored. 

• ATDEF — The argument specified for the "defalt" parameter is the 
address of a location containing the default value. 

• ATLO — The argument specified for the "lolim" parameter is the 
address of a location containing the low limit value. 

• ATHI — The argument specified for the "hilim" parameter is the 
address of a location containing the high limit value. 

By default, all flags are cleared. 



RETURN 
STATUS 



SS$_NORMAL 
DS$_PROGERR 



Service successfully completed. 

An Incorrect number of arguments was supplied with 
the macro. 
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NOTES 



If the VDS control flag OPERATOR is dear and if no default value has 
been specified for the prompting message, the diagnostic program will 
be aborted. Thus, if the diagnostic program is intended to be executed 
in an automated run-time envirorunent (such as APT), these macros 
cannot be used unless default values are provided. 

It is also required that if these macros are used in the DEFAULT 
program section (see Section 3.8.3), default values must be provided. 

If the VDS control flag PROMPT is set, the ranges and default values 
for user responses will be displayed along with the prompting message. 

To ensure that prompting messages are left-justified, precede each 
prompting message with a CR and LF. 

See Figure 5-2, Valtab Table Format, in the $DS_ASKADR macro 
section. 

In a multiprocessing environment, $DS_ASKLGCL cannot be called 
from within a block of code delineated by the $DS_BGNATTACHED 
and $DS_ENDATTACHED macros. 



MACRO-32 
EXAMPLE 



PROMPT : 
RESPONSE ! 



.ASCIC /DEVICE ADDRESS:/ 
.LONG 



$DS_ASKLGCL_S - 

MSGADR = PROMPT, - 
DATADR = RESPONSE 



BUSS-32 
EXAMPLE 



BIND 



PROMPT = UPLIT (%ASCIC 'IS THE DRIVE WRITE-ENABLED? ) ; 



LOCAL 

RESPONSE; 



$DS_ASKLGCL ( HSGADR=PR0MPT , DATADR=RESPONSE ) ; 
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$DS ASKSTR 



The $DS_ASKSTR system service is used to obtain information from the 
program user at run time. With these services, the diagnostic program can 

• Prompt the user with a message specified by the programmer 

• Obtain l^eyboard input from the user 

• Interpret and validate the input string 

• Store the value specified by the input string 

The Ask for Character String ($DS_ASKSTR) system service is used to 
obtain an alphabetic character string from the user. Optionally, the caller 
can also provide a set of valid response strings. The system sen/ice will 
compare the input string to the valid responses and indicate to the caller 
which response was provided. 



IVIACRO-32 



BLISS-32 



$DS_ASKSTR_x msgadr, bufadr, [maxlenj, [valtab], 

[defadr] 



$DS_ASKSTR (MSGADR = msgadr, 
BUFADR = bufadr, 
[MAXLEN = maxlen], 
[VALTAB = valtab], 
[DEFADR = defadr]); 



ARGUMENTS 



msgadr 

Address of counted ASCII string to be used as user prompting message. 

datadr 

Address of longword to receive interpreted user response value. 

bufadr 

Address of buffer that will receive counted ASCII input string. 

maxlen 

Size of the buffer specified in "bufadr." The default value is 72. 

valtab 

Address of table containing list of string pointers. See Note 4 for table 
format. Each table entry points to a counted ASCII string that represents 
a valid user response. The system service will compare actual user input 
to the valid responses. If a match is found, the number of the table entry 
pointing to the matched string will be returned in Rl. If a match is not 
found, the system service will inform the user that an invalid response has 
been issued and will then reissue the prompt message. 
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If this parameter is (ttxe default), no validation will take place. 

defadr 

Address of counted ASCII string to be used as a default user response. 
The default value for this parameter is 0, which ineans there is no default 
user response. 

radix 

Radix in which the user response is to be interpreted. Legal values for 
this parameter are defined by the macro $DS_PARDEF, and consist of 
PAR$_BIN, PAR$_OCT, PAR$_DEC, and PAR$_HEX. The default radix is 
decimal. 

lolim 

Minimum acceptable value for numeric user reponse. Default is minus 2 to 
the 31st power. 

hilim 

Maximum acceptable value for numeric user response. Default is 2 to the 
31st power minus 1. 

defalt 

The value to be used if the user does not provide a response (user only 
types return key). The default value for "defalt" is 0. If no default is to be 
used, then NODEF must be set in the "exword" parameter. 

unused 

Reserved for expansion. 

exword 

The "exception mask." This is a longword containing "exception 
flags." These flags are used to modify the interpretations of some of 
the other parameters. Symbols for the exception flags are defined by 
the $DS_PARDEF macro. Refer to the description of that macro for the 
complete symbol names. The flags are: 

• NODEF — There is to be no default value for the user response. In 
other words, the "defalt" parameter is to be ignored. 

• ATDEF — The argument specified for the "defalt" parameter is the 
address of a location containing the default value. 

• , ATLO — The argument specified for the "lolim" parameter is the 

address of a location containing the low limit value. 

• ATHI — The argument specified for the "hilim" parameter is the 
address of a location containing the high limit value. 

By default, all flags are cleared. 



RETURN 
STATUS 



SS$_NORMAL 
DS$_PROGERR 



Service successfully completed. 

An Incorrect number of arguments was supplied witti 
the macro. 
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DS$_TRUNCATE 



The string supplied by tlie user was too long to fit 
into ttie buffer pointed to by "bufadr." The string 
was truncated in order to fit into the buffer. 



NOTES 



If the VDS control flag OPERATOR is clear and if no default value has 
been specified for the prompting message, the diagnostic program will 
be aborted. Thus, if the diagnostic program is intended to be executed 
in an automated run-time environment (such as APT), these macros 
cannot be used unless default values are provided. 

It is also required that if these macros are used in the DEFAULT 
program section (see Section 3.8.3), default values must be provided. 

If the VDS control flag PROMPT is set, the ranges and default values 
for user responses will be displayed along with the prompting message. 

To ensure that prompting messages are left-justified, precede each 
prompting message with a CR and LF. 

See Figure 5-2, Valtab Table Format, in the $DS_ASKADR macro 
section. 

In a multiprocessing environment, $DS_ASKSTR cannot be called from 
within a block of code delineated by the $DS_BGNATTACHED and 
$DS_END ATTACHED macros. 



MACRO-32 
EXAMPLE 



PROMPT ; 
RESPONSE ! 



.ASCIC /DEVICE ADDRESS:/ 
.LONG 



SDS_ASKSTR_S - 

MSGADR = PROMPT, - 
DATADR = RESPONSE, - 
MAXLEN = #5 



BLISS-32 
EXAMPLE 



BIND 



PROMPT = UPLIT (%ASCIC 'IS THE DRIVE WRITS-ENABLED?); 

LOCAL 

RESPONSE; 



$DS_ASKSTR (MSGADR=PROMPT, DATADR=RESPONSE , MRXLEN=5); 
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$DS^ASKVLD 



The $DS_ASKVLD system service is used to obtain information from the 
program user at run time. With these services, the diagnostic program can 

• Prompt the user with a message specified by the programmer 

• Obtain l<eyboard input from the user 

• Interpret and validate the input string 

• Store the value specified by the input string 

The Ask for Data Field ($DS_ASKVLD) system service is used to obtain a 
numeric value from the user and insert the value into a data field indicated 
by a position and size. This service is useful for loading fields in large data 
structures (greater than 32 bits). 



MACRO-32 



$DS_ASKVLD_x msgadr, datadr, [radix], [pos], [size], 

[lolim], [hilim], [defalt], [unused], 
[exword] 



BLISS-32 



$DS_ASKVLD (l\/ISGADR = msgadr, 

DATADR = datadr, 
[RADIX = radix], 
[POS = pos], 
[SIZE = size], 
[LOLIM = lolim], 
[HILIM = hilim], 
[DEFALT = defalt], 
[EXWORD = exword]); 



ARGUMENTS 



msgadr 

Address of counted ASCII string to be used as user prompting message. 

datadr 

Address of longword to receive interpreted user response value. 

Value is placed in field indicated by "pos" and "siz," where "pos" is bit 

offset from "datadr." 

radix 

Radix in which the user response is to be interpreted. Legal values for 
this parameter are defined by the macro $DS_PARDEF, and consist of 
PAR$_BIN, PAR$_OCT, PAR$_DEC, and PAR$_HEX. The default radix is 
decimal. 
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pos 

Bit offset from "datadr," indicating where interpreted user response is to 
be stored. Default is 0, indicating value should be stored starting at bit of 
"datadr." Legal range normally is through the largest value that can be 
stored in a longword. However, if a register is specified for "datadr," then 
the legal range for "pos" is through 31. 

size 

Number of bits in "datadr" in which interpreted user response is to be 
stored. Range is 1 tlirough 32. 

lollm 

Minimum acceptable value for numeric user reponse. Default is minus 2 to 
the 31st power. 

hilim 

Maximum acceptable value for numeric user response. Default is 2 to the 
31st power minus 1. 

defalt 

The value to be used if the user does not provide a response (user only 
types return key). The default value for "defalt" is 0. If no default is to be 
used, then NODEF must be set in the "exword" parameter. 

unused 

Reserved for expansion. 

exword 

The "exception mask." This is a longword containing "exception 
flags." These flags are used to modify the interpretations of some of 
the other parameters. Symbols for the exception flags are defined by 
the $DS_PARDEF macro. Refer to the description of that macro for the 
complete sjnnbol names. The flags are: 

• NODEF — There is to be no defauU value for the user response. In 
other words, the "defah" parameter is to be ignored. 

• ATDEF — The argument specified for the "defalt" parameter is the 
address of a location containing the default value. 

• ATLO — The argument specified for the "lolim" parameter is the 
address of a location containing the low limit value. 

• ATHI — The argument specified for the "hilim" parameter is the 
address of a location containing the high limit value. 

By default, all flags are cleared. 
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RETURN 
STATUS 



SS$_NORMAL 
DS$_PROGERR 

DS$_TRUNCATE 



Service successfully completed. 

An incorrect number of arguments was supplied with 
the macro. 

The value specified by the user was too large to fit 
into the bit field specified by the caller. The value 
was truncated in order to fit into the specified field. 



NOTES 



If the VDS control flag OPERATOR is clear and if no default value has 
been specified for the prompting message, the diagnostic program will 
be aborted. Thus, if the diagnostic program is intended to be executed 
in an automated run-time environment (such as APT), these macros 
cannot be used unless default values are provided. 

It is also required that if these macros are used in the DEFAULT 
program section (see Section 3.8.3), default values must be provided. 

If the VDS control flag PROMPT is set, the ranges and default values 
for user responses will be displayed along with the prompting message. 

To ensure that prompting messages are left-justified, precede each 
prompting message with a CR and LP. 

See Figure 5-2, Valtab Table Format, in the $DS_ASKADR macro 
section. 

In a multiprocessing environment, $DS_ASKVLD cannot be called from 
within a block of code delineated by the $DS_BGNATTACHED and 
$DS_ENDATTACHED macros. 



MACRO-32 




EXAMPLE 




PROMPT; .ASCIC /DEVICE 


RESPONSE: .LONG 


$DS ASKVLD S - 




MSGADR = 


PROMPT, - 


DATADR = 


RESPONSE , 


RADIX = 


#PAR$ DEC, 


PCS 


#0, - 


SIZE 


#4, - 


LOLIM = 


#1, - 


HILIM = 


#3 



5-27 



$DS_ASKVLD 



BLISS-32 
EXAMPLE 



BIND 

PROMPT = UPLIT (%ASCIC 'IS THE DRIVE WRITE-ENABLED? ) ; 

LOCAL 

RESPONSE; 



$DS_ASKVLD (MSGADR = PROMPT, 

DATADR = RESPONSE, 

RADIX = PAR$_DEC, 

POS = 0, 

SIZE = 4, 

LOLIM = 1, 

HILIM =3); 
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$ASSIGN 



The Assign I/O Channel system service of VIVIS is used to provide an i/0 
channel that can be used by the caller to communicate with a peripheral 
device in user mode. Level 2R programs must issue the $ASSIGN macro 
before the $Q10 macro can be used. Refer to Section 5.3 for details of I/O 
operations in user mode. 

This service can also be used to create a logical link with a remote node 
on a network. Refer to the DECnet-VAX User's Guide for details. 



MACRO-32 



$ASSIGN_x devnam, chan, [acmode], [mbxnam] 



BLISS-32 



$ASSIGN (DEVNAM = devnam, CHAN = chan, 
[ACMODE = acmode], 
[MBXNAM = mbxnam]); 



ARGUMENTS 



devnam 

Address of a character string descriptor (see Section 5.3) pointing to the 
device name string. The string may be either a physical device name or a 
logical name. If the first character of the string is an underscore (_), the 
name is a physical name. Otherwise, one level of logical name translation 
is. performed and the equivalence name, if any, is used. 

If the device name contains a double colon (::), VMS assigns a channel to 
the device NETO: and performs an access function on the netv^ork. 

chan 

Address of a longword to receive the channel number assigned. 

acmode 

Access mode to be associated with the channel. The specified access 
mode is maximized with the access mode of the caller. I/O operations on 
the channel can only be performed from equal and more privileged access 
modes. Legal values are for Kernel, 1 for Executive, 2 for Supervisor, and 
3 for User. 

mxbnam 

Address of a character string descriptor (see Section 5.3) pointing to the 
logical name string for the mailbox to be associated with the device, if 
any. The mailbox receives status information from the device driver. An 
address of implies no mailbox. This is the default value. 
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RETURN 
STATUS 



SS$_NORMAL 
SS$_REMOTE 

SS$_ABORT 

SS$_ACCVIO 

SS$_DEVACTIVE 

SS$_DEVALLOC 

SS$_DEVNOTMBX 

SS$_EXQUOTA 

SS$JNSFMEM 

SS$_IVDEVNAM 



SS$JVLOGNAM 

SS$_NOIOCHAN 

SS$_NOLINKS 

SS$_NOPRIV 

SS$_NOSUCHDEV 

SS$_NOSUCHNODE 

SS$_REJECT 



Service successfully completed. 

Service successfully completed. A logical link Is 
established witii the target on a remote node. 

A physical line went down during a network correct 
operation. 

A device or mailbox name string or string descriptor 
cannot be read by the caller, or the channel number 
cannot be written by the caller. 

A mailbox name has been specified, but a mailbox 
is already associated with the device. 

Warning. The device is allocated to another 
process. 

A logical name has been specified for the associated 
mailbox, but the logical name refers to a device that 
Is not a mailbox. 

The target of the assignment is on a remote node 
and the process has insufficient buffer quota to 
allocate a network control block. 

The target of the assignment is on a remote node, 
and there is insufficient dynamic system memory to 
complete the request. 

No device name was specified, or the device or 
mailbox name string contains Invalid characters. If 
the device name is a target on a remote node, this 
status code indicates that the Network Control Block 
has an invalid format. 

The device or mailbox name string has a length of 
or has more than 63 characters. 

No I/O channel is available for assignment. 

No logical network links are available. 

The process does not have the privilege to perform 
network operations. 

Warning. The specified device or mailbox does not 
exist. 

The specified network node is nonexistent or 
unavailable. 

The network connect was rejected by the network 
software or by the partner at the remote node; or 
the target image exited before the connect confirm 
could be issued. 



NOTES 



Refer to the VAX/VMS System Services Reference Manual for notes on the 
$ASSIGN system service. This manual should be read before attempting 
I/O operations in user mode. 
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MACRO-32 
EXAMPLE 



TTNAME: .ASCID /TTA2 : / .-TERMINAL DESCRIPTOR 
TTCHAN: .BLKL 1 ; TERMINAL CHANNEL NUMBER 



$ASSIGN S DEVNAM=TTNAME, CHAN=TTCHAN 



BLiSS-32 
EXAMPLE 



BIND 

TTNAME = UPLIT (%ASCID ' TTA2 ! ' ) ; 

OWN 

TTCHAN : VECTOR; 



$ASSIGN ( DEVNAM= . TTNAME , CHAN=TTCHAN ) ; 
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$DS_ATTACH 



The Attach Device system service can be used to "attach" a device 
automatically from within the diagnostic program, instead of requiring 
the program user to issue the ATTACH command. Attaching devices is 
discussed in Section 3.2. An example of when it might be desirable to use 
the $DS_ATTACH macro is the case in which record management services 
(RMS) are to be used to reference a file on a device other than the VDS 
default load device. 



MACRO-32 $DS_ATTACH_x cmd, [pmt] 



BLISS-32 



$DS_ATTACH (CMD = cmd, [PMT = pmt]); 



ARGUMENTS 



cmd 

Address of a quadword descriptor that points to a valid ATTACH 
command argument string. If the argument string does not contain every 
necessary response to each ATTACH prompt, the "pmt" parameter must 
also be specified. (The argument string should not include prompting 

strings). 

pmt 

Address of a quadword descriptor pointing to a buffer that will receive 
error messages and prompting messages if the command string pointed 
to by "cmd" is incomplete or in error. This parameter is optional only if 
the programmer is absolutely sure that the specified command string will 
always be correct for any hardware configuration. Using the contents of 
this buffer is discussed in Note 1. 



RETURN 
STATUS 



SS$_NORMAL 
DS$_BADTYPE 

DS$_BADLINK 

DSSJLLUNIT 

DS$_DEVNAME 

SS$_BADPARAM 

SSSJNSFARG 



Service successfully completed. 

An Invalid device type was specified in the argument 
string. 

The device link specified in the argument string is 
not attached. 

The device unit number was required and not given, 
or was too large. 

The device name specified in the argument string Is 
invalid. 

A numeric argument was specified in an invalid radix 
or was out of range. 

The argument string was incomplete. 
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NOTES 



If an argument in the argument string is invalid, or if the argument 
string is incomplete, the following will occur: 

a. One of the error status codes will be returned. 

b. The length field of the quadword descriptor pointed to by "cmd" 
will be altered to reflect the length of the valid portion of the 
argument string. 

C. The buffer described by "pmt" will contain a VDS-generated error 
message and the user prompt for the invalid or missing argument. 

The contents of the "pmt" buffer can be used as the prompting 
string'C'msgadr" parameter) of a $DS_ASKSTR macro. The user's 
response could then be added to the argument string, after the last 
valid argument. The argument string's size would then be readjusted 
and the $DS_ ATTACH macro would be reissued. (Note that a p-table 
is not actually built until all arguments are valid, so this process can be 
repeated until the user has supplied a complete argument string.) This 
service will not display any information on the user's terminal. Thus if 
an error occurs, simply using $DS_ASKSTR macro to display the error 
message and prompt is insufficient, since the user will have no idea 
what device is being attached! It will be necessary for the program to 
display an explanatory message indicating (1) that an attach was being 
attempted and (2) which device was being attached. 



MACRO-32 
EXAMPLE 



CHOLINE; 



.ASCID /RH780 SBI RHO 8 5/ 



$DS ATTACH_S CHOLINE; 



BLISS-32 
EXAMPLE 



BIND 



CHOLINE = UPLIT (%ASCID 'RH780 SBI RHO 8 5') I 



$DS_ATTACH ( CMO= . CHOLINE ) ; 
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$DS_BCOMPLETE 



The $DS_BCOMPLETE and $DS_BNCOMPLETE program control macros 
can be used to test the return status of a system service (or any routine 
which returns a status code in RO) and branch if the service's operation 
was "complete" or "incomplete." 



MACRO-32 



$DS_BCOMPLETE adr 



BLISS-32 



Not supported for BLISS-32, since testing RO is implicit in the ianeuaee 
See the example below. 



ARGUMENTS adr 

Address to branch to if tested condition is satisfied. 



NOTES 



1 For all error status codes, bit is clear. Therefore, this macro simply 
generates the following code: 

$DS_BCOMPLETE - BLBS RO,adr 

2 If an error stahis code is detected, the contents of RO should be 
compared with all error codes that could possibly be returned from 
the service (or other) routine to determine the exact nature of the error. 



MACRO-32 
EXAMPLE 



$DS_GETBUF 
$DS BCOMPLETE 



#2, RETADDR, PHYSADDR 
GOOD BUF 



BLISS-32 
EXAMPLE 

IF $DS_GETBUF ( PAGCNT=2 ) THEN 
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$DS_BERROR 



The $DS_BERROR and $DS_BMERROR program control nracros can be 
used to test the return status of a system service (or any routine which 
returns a status code in RO) and branch if the service's operation was in 
error or was error-free. 



MACRO-32 



$DS_BERROR adr 



BLISS-32 



Not supported for BLISS-32, since testing RO is implicit in the language. 
See the example below. 



ARGUMENTS adr 



Address to branch to if tested condition is satisfied. 



NOTES 



For all error status codes, bit is clear. Therefore, this macro simply 
generate the following code: 

$DS_BERROR - BLBC RO,adr 

If an error status code is detected, the contents of RO should be 
compared with all error codes that could possibly be returned from 
the service (or other) routine to determine the exact nature of the error. 



MACRO-32 
EXAMPLE 



$DS_GPHARD 
SDS BERROR 



LOG_UNIT, ADDRl 
10$ 



BLISS-32 
EXAMPLE 

IF NOT $DS_GPHARD (UNIT=.LOG_UNIT, RETADR=ADDR1 ) THEN .. 
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$DS_BGNATTACHED— $DS_ENDATTACHED 

In a diagnostic program tliat tests multiple processors, use the 
$DS_BGNATTACHED and $DS_ENDATTACHED macros to delineate 
code that is to be executed in an attached processor. These macros 
are used whether the code is included in the loadable image of the main 
diagnostic program or it is a separate loadable image. (See Section 4.6.) 

$DS_BGNATTACHED indicates the beginning of the code and creates 
a label that can be used with the $DS_STARTATTACHED service. The 
$DS_ENDATTACHED macro generates code that will send the processor 
bacl< to its idle loop. 



MACRO-32 



$DS_BGN ATTACHED routine_name, mask 



$DS_ENDATTACHED 



BLISS-32 



$DS_BGNATTACHED 

(ROUTINE_NAME = routine_name); 



$DS_ENDATTACHED; 



ARGUMENTS routine_name 

Labels the routine and points to its first instruction. 

mask 

List of register names used in the entry mask. 
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NOTES 



1 You can include code that is contained in an attached process in 
any number of separate executable files. The code in each file, 
however, must be position-independent. You can only have one 
attached process, delimited by one set of $DS_BGNATTACHED and 
$DS_END ATTACHED macros, per file. 

2 If you want to place the code in a separate image, request a buffer 
using the $DS_GETBUF service, load the image into the buffer, and 
use the address of the buffer as the "start_addr" argument for the 
$DS_STARTATTACHED macro. 

3 You can enter the code using a CALL instruction. 

4 It is recommended that you place data structures for the code in a 
separate psect. If you must include the data structures in the same 
psect as the code, place them (data structures) after the code and end 
the executable section with a $DS_EXIT macro as shown: 

.psect data $DS_BGNATTACHED RTN2 

<data structures> 

<executable code> 

.psect code 

$DS BGNATTACHED RTNl $DS_EXIT ATTACHED 



<executable code> <data structures> 



$DS ENDATTACHED SDS_ENDATTACHED 
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$DS_BGNCLEAN— $DS_ENDCLEAN 



The $DS_BGNCLEAN and $DS_ENDCLEAN macros are used to delimit 
the program's clean-up code. These macros create the connections which 
make it possible for the VDS to locate and execute the clean-up code. 



IViACRO-32 



$DS_BGNCLEAN [<regmask>J, [<psect>} 

(clean-up code) 
$DS_ENDCLEAN 



BLISS-32 



$DS_BGNCLEAN; (clean-up code); 
$DS_ENDCLEAN; 



ARGUMENTS 



regmask 

List of general purpose register names to be placed in the entry mask. 

psect 

Any argument string that is valid for a MACRO-32 .PSECT statement. If 
none is specified, the argument string "CLEANUP, LONG" will be used. 



NOTES 



1 In MACRO-32, the $DS_BGNCLEAN macro will generate the following 
code: 



CLEAN UP: 



.SAVE 
.PSECT psect 

.WORD '^M<regniask> 



In MACRO-32, the $DS_ENDCLEAN macro will generate the following 
code: 



CLEAN UP X: 



$DS_BREAK 

RET 

. RESTORE 



2 In BLISS-32, the $DS_BGNCLEAN macro will generate the following 
code: 



%SBTTL 'CLEAN UP' 

PSECT CODE = CLEANUP (WRITE); 

GLOBAL ROUTINE CLEAN UP;NOVALUE = 

BEGIN 



In BLISS-32, the $DS_ENDCLEAN macro will generate the following 
code: 



END 
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MACRO-32 
EXAMPLE 

$DS_BGNCLEAN <R2 , R3 , R4, R5>, <CLEANSECT,LONG> 



$DS ENDCLEAN 



BLISS-32 
EXAMPLE 

$DS BGNCLEAN; 



$DS_ENDCLEAN ; 
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$DS_BGNDATA— $DS_ENDDATA 



The $DS_BGNDATA and $DS_ENDDATA macros are used to optionally 
provide lists of input arguments to a test. Each time the VDS executes a 
test for which argument lists have been specified, it will execute the code 
within the test once for each argument list. From the user's point of view, 
this repeated execution of the code within a test will appear to be one 
execution of the test. 

The $DS_BGNDATA and $DS_ENDDATA macros must be located 
immediately before the $DS_BGNTEST macro of the test to which the 
parameter lists belong. 



MACRO-32 



$DS_BGNDATA [align], argument-list, [argument-list] 



$DS_ENDDATA 



BLISS-32 



This macro is not supported for BLISS-32. 



ARGUMENTS align 



Desired alignment for the psect containing the argument lists. Possible 
values are BYTE, WORD, LONG, QUAD, PAGE, or an integer from to 
9. If an integer is specified, the psect will start at the next address that is a 
multiple of two raised to the power of the integer. 

argument-list 

A list of arguments to be used by the test. Each argument must occupy a 
longword. Each parameter list must be formatted as shown in Figure 5-3. 
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Figure 5-3 Argument List Format for $DS_BGNDATA 



31 





N 


ARGUMENT 1 


ARGUMENT 2 


' • ' 


ARGUMENT N 



ZK-4791-85 



$DS_ENDDATA 

The $DS_ENDDATA will provide termination for the set of lists by 
generating a longword of 0. 



NOTES 



The VDS will call the test code with a CALLG instruction. Each time 
the test is called, the address of the next argument list will be used as 
the CALLG instruction's argument list parameter. Thus the arguments 
can be referenced within the test by offsets from the AP. 



EXAMPLES 



$DS_BGNDATA 

• LONG 
.LONG 
.LONG 

$DS_ENDDATA 



4, DATA_1, DATA_2, DATA_3, DATA_4 
4, DATA_5, data" 6, DATA_7 , DATA_8 
4, DATA_1, DATA_3, DATA_7 , DATA_9 
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$DS_BGNrN!T— $DS^ENDINIT 

The $DS_BGNINIT and $DS_ENDIN!T macros are used to delimit the 
diagnostic program's initialization code. These macros create the 
connections that make it possible for the VDS to locate and execute 
the initialization code. 



MACRO-32 



$DS_BG N IN rr [< regmask_ >], [< psect_ >] 

(initialization code) 
$DS_ENDINiT 



BLlSS-32 



$DS_BGNINIT; (initialization code); 
$DS_ENDINIT; 



ARGUMENTS 



regmask 

List of general purpose register names to be placed in the entry mask. 

psect 

Any argument string that is valid for a MACRO-32 .PSECT statement. If 
none is specified, the argument string "INITIALIZE, LONG" wll be used. 



NOTES 



In MACRO-32, the $DS_BGNINIT macro wiU generate the following 
code: 



INITIALIZE: 



.SAVE 
.PSECT psect 

.WORD '^M<regmask> 



In MACRO-32, the $DS_ENDINIT macro wiU generate the following 
code: 



IHITIALIZE_X: 

SDS_BREAK 

RET 

• RESTORE 

2 In BLISS-32, the $DS_BGNINrr macro will generate the following code: 

%SBTTL 'INITIALIZE' 

PSECT CODE = INITIAI,IZE(WRITE); 

GLOBAL ROUTINE INITIALIZE ! NOVALUE = 

BEGIN 

In BUSS-32, the $DS_ENDINIT macro will generate the following code: 

$D5_BREAKj 
END 
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IVIACRO-32 
EXAMPLE 



$DS_BGNINIT R2,R3,R4,R5, INITSECT, LONG 



$DS ENDINIT 



BLISS-32 
EXAMPLE 

$DS BGNINIT; 



$DS ENDINIT; 
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$DS_BGNMESSAGE— $DS_ENDMESSAGE 



The $DS_BGN MESSAGE and $DS_ENDMESSAGE macros should be used 
to delimit each error reporting routine used in conjunction with the error 
reporting macros ($DS_ERRxxxx). 



MACRO-32 



$DS_BGNMESSAGE [<regmask>] 

(error reporting routine) 
$DS_ENDMESSAGE 



BLISS-32 



$DS_BGNMESSAGE 

(ROUTINEJiAME = routine_name); 
(error reporting routine); 
$DS_ENDMESSAGE: 



ARGUMENTS 



regmask 

List of general purpose register names to be placed in the entry mask. 

routlne^name 

Symbolic name to be associated with the error reporting routine. 



NOTES 



The error reporting routine must use $DS_PRINTB and $DS_PRINTX 
macros to print messages. The most important information should 
be printed first, using $DS_PRINTB macros. The most detailed 
information, such as dumps of device registers, should be printed 
last, using $DS_PRINTX macros. Refer to Section 3.9.1, Error Message 
Formats, for example error messages. 

Further details on error reporting routines are listed in the description 
of the error macros ($DS_ERRxxxx). 

In MACRO-32, the $DS_BGNMESSAGE macro generates an entry 
mask. The $DS_ENDMESSAGE macro generates a RET instruction. 

In BLISS-32, THE $DS_BGNMESSAGE macro generates the following 
code: 

GLOBAL ROUTINE %NAME(routine_nanie) (NUM, UNIT, MSGADR, PRLINK, 

PI, P2, P3, P4, P5, P6) : NOVALUE = 
BEGIN 

The $DS_ENDMESSAGE macro generates the following code: 

RETURN 
END 
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$DS_BGNMESSAGE 



EXAMPLE Refer to the description of the $DS_ERRxxxx macros (later in this chapter) 

for examples of $DS_BGNMESSAGE and $DS_ENDMESSAGE. 
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$DS_BGNMOD— $DS_ENDMOD 



The $DS_BGNMOD and $DS_ENDMOD macros must be included at the 
beginning and end, respectively, of every source moduie mal<ing up the 
diagnostic program. 



MACRO-32 



$DS_BGNMOD [env], [tn], [st] 

(source module) 
$DS_ENDMOD 



BLISS-32 



$DS_BGNMOD ([ENV=evnJ, [TEST=tn]); 

(source module); 
$DS_ENDIViOD; 



ARGUMENTS env 

Used to indicate if the program is a level 2 program. If so, this value must 
be 2. Otherwise, the value should be (the default). 

Note: In the past, this parameter was assigned one of four predefined 

values: CEP_FUNCTIONAL, CEP_REPAIR, SEP_FUNCTIONAL, or 
SEP_REPAIR. These symbols are meaningless and should not be used. 
(SEP_FUNCTIONAL) is equivalent to 2. 

tn 

Value representing the number to be assigned to the first test in this 
module, if this module contains tests. Default value is 1. 

St 

Value representing the number to be assigned to the first subtest in this 
module, if this module contains subtests. Default value is 1. 



NOTES 



In BLISS-32, the $DS_BGNMOD and $DS_ENDMOD macros must be 
contained within the bounds of the MODULE and ELUDOM keywords, 
as follows. 



MODULE modnam = 
BEGIN 



$DS_BGNMOD ( ) ; 



$DS_ENDMOD; 

END 

ELUDOM 
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$DS_BGNREG~$DS_ENDREG 



The $DS_BGNREG and $DS_ENDREG macros may be used to delimit a 
storage area in whicli device register contents are placed. 



IVIACRO-32 



$DS_BGNREG (register storage area) 
$DS_ENDREG 



BLISS-32 



$DS_BG N R EG ; (register storage area); 
$DS_ENDREG; 



NOTES 



1 In MACRO-32, the $DS_BGNREG macro generates the label 
"DEVREG:." 

In BLISS-32, the $DS_BGNREG macro generates the statement 

OWN DEV_REG : VECTOR [0]; 

2 The $DS_ENDREG does not generate any source code. 
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$DS_^BGNSERV— $DS_ENDSERV 



The $DS_BGNSERV and $DS_ENDSERV macros should be used to 
delimit interrupt service routines. 



MACRO-32 



$DS_BGNSERV addr 

(interrupt service routine) 
$DS_ENDSERV 



BLISS-32 



These macros are niot supported for BLISS-32. 



ARGUMENTS addr 



Symbolic name to be associated with the interrupt service routine. 



NOTES 



1 The $DS_BGNSERV macro will generate the following code: 

.ALIGN LONG, ; ALIGN ON LONGWORD BOUNDARY 
ADDR: 

PUSHR #'^M<R0,R1> ; SAVE RO AND Rl 

The $DS_ENDSERV macro will generate the following code: 



POPR 
RE I 



#'>M<R0,R1> 



RESTORE RO AND Rl 
RETURN FROM SERVICE 
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$DS_BGNSTAT— $DS_ENDSTAT 



The $DS_BGNSTAT and $DS_ENDSTAT macros should be used to delimit 
the data storage area referenced by the summary routine (see Section 3.7, 
Summary Routines). This data area should contain a set of error counts 
for each unit under test. Thus there must be enough storage space 
allocated to handle the maximum number of device units the diagnostic 
program can test. 



MACRO-32 



$DS_BGNSTAT 
$DS_ENDSTAT 



(statistics tables) 



BLISS-32 



$DS_BGNSTAT; (statistics tables); 
$DS_ENDSTAT; 



NOTES 



In MACRO-32, the $DS_BGNSTAT macro simply generates the label 
'STATISTIC:'. The $DS_ENDSTAT does not generate any code. 

In BLISS-32, the $DS_BGNSTAT macro generates the following 
statement: 

GLOBAL STATISTIC : VECTOR [0]; 

The $DS_ENDSTAT macro does not generate any code. 
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$DS^BGNSUB"-$DS_ENDSUB 



The $DS_BGNSUB and $DS_ENDSUB macros are used to delimit eacli 
subtest existing In any particular test. Refer to Section 3.8, Tests, 
Subtests, and Sections, for a discussion of subtests. 



MACRO-32 



$DS_BGNSUB 
$DS_ENDSUB 



(subtest) 



BLISS-32 



$DS_BGNSUB; 
$DS_ENDSUB; 



(subtest); 



NOTES 



The macro automatically numbers each subtest. Subtests are numbered 
from 1 to N for each test, where N is the total number of subtests 
within the test. 

The $DS_BGNSUB macro generates a call to a VDS routine that will 
record the numbers of the current test and subtest. The $DS_ENDSUB 
macro will generate a call to a VDS routine that will verify that the 
current test and subtest numbers are the same as those stored when 
the $DS_BGNSUB macro was issued. If the numbers do not match, the 
VDS will stop execution of the diagnostic program. 
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$DS_BGNSUMMARY— $DS_ENDSUMMARY 

The $DS_BGNSUMMARY and $DS_ENDSUMMARY macros are used 
to delimit tlie summary routine. Summary routines are discussed in 
Section 3.7. 



MACRO-32 



$DS_BGNSUIVIMARY [<regmask>], [<psect>] 

(summary routine) 
$DS_ENDSUMMARY 



BLISS-32 



$DS_BGNSUIVIMARY; (summary routine); 
$DS_ENDSUMMARY; 



ARGUMENTS 



regmask 

List of general purpose register rxames to be placed in the entry mask. 

psect 

Any argument string that is valid for a MACRO-32 .PSECT statement. If 
none is specified, the argument string 'SUMMARY,LONG' will be used. 



NOTES 



1 In MACRO-32, the $DS_BGNSUMMARY macro will generate the 
following code: 



SUMMARY: 



.SAVE 
. PSECT psect 

WORD '^M<regmask> 



; ENTRY MASK 



In MACRO-32, the $DS_ENDSUMMARY macro will generate the 
following code: 



SOMMARY_X: 

$DS_BREAK 

RET 

. RESTORE 



In BLISS-32, the $DS_BGNSUMMARY macro will generate the 
following code: 



PSECT CODE = SUMMARY (WRITE); 
GLOBAL ROUTINE SUMMARY : NOVALUE 
BEGIN 



In BLISS-32, the $DS_ENDSUMMARY macro will generate the 
following code: 



$DS_BREAK; 
END 
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$DS_BGNTEST— $DS^ENDTEST 



The $DS_BGNTEST and $DS_ENDTEST macros are used to delimit each 
test existing in a diagnostic program. Tests are discussed in Section 3.8, 
Tests, Subtests, and Sections. 



MACRO-32 



$DS_BGNTEST [<section-name,section-name,... >], 

[< regmask >], [align] 

(test code) 
$DS_ENDTEST 



BLISS-32 



$DS_BGNTEST 



$DS_ENDTEST; 



([SECTION =< section-name, 
section-name,... >], 
[TEXT = 'test-name']); 
(test code); 



ARGUMENTS 



section-name 

Name of a program section to which this test belongs. Refer to Section 3.8, 
Tests, Subtests, and Sections. 

regmask 

List of general purpose register names to be placed in the entry mask. 

align 

Desired alignment for the psect containing the argument lists. Possible 
values are BYTE, WORD, LONG, QUAD, PAGE, or an integer from to 
9. If an integer is specified, the psect will start at the next address that is a 
multiple of two raised to the power of the integer. 

text 

Text string identifying the test. This test will be displayed on the user 
terminal each time the test is executed, provided that the user has set the 
VDS control flag TRACE. If the (') character is to be included within the 
text string, it must be specified twice, as in: 

TEXT = 'Fred"s test' 

(In MACRO-32, the identif3nng message is defined by using the 
$DS_SUBTTL macro.) 



5-52 



$DS_BGNTEST 



NOTES 



The $DS_BGNTEST macro will assign a test number to the test. The 
test number is incremented each time the $DS_BGNTEST macro is 
called within a source module. (The test number can be initialized 
when the $DS_BGNMOD macro is called at the beginning of the 
source module.) 

In MACRO-32, the $DS_BGNTEST macro causes the following label to 
be generated: 

TEST_xxx : : . WORD ■^M< > 

where "xxx" is the current test number. 

In MACRO-32, the $DS_ENDTEST macro generates the following code: 

MOVL #1,R0 ; NORMAL EXIT 
TEST_nnn_X! : 

$DS_BREAK 
RET 

In BLISS-32, the $DS_BGNTEST macro generates the following entry 
point: 

.ENTRY TEST_xxx , '"M< > 

where "xxx" is the current test number. 

In BLISS-32, the $DS_ENDTEST macro generates the following code: 

$DS_BREAK; 
SS$_NORMAL 
END; 

$DS_BGNTEST and $DS_ENDTEST are unavailable to attached 
processors in multiprocessing environments. 
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$BINTIM 



The Convert ASCII String to Binary Time system service converts an ASCII 
string to an absolute or offset time value in the system 64-bit time format 
suitable for input to the $SETIMR service. 



MACRO-32 



$BINTIM_x timbuf, timadr 



BLISS-32 



$BINTIM (TIMBUF = timbuf, TIMADR = timadr); 



ARGUMENTS 



timbuf 

Address of a character string descriptor (see Section 5.3) pointing to the 
buffer containing the absolute or offset time to be converted. See notes for 
input string format. 

The maximum offset time that may be specified is 10,000 days. 

timadr 

Address of a quadword to receive the converted time in 64-bit format. 



RETURN 
STATUS 



SS$_NORMAL 
SS$_IVTIME 



Service successfully completed. 

Syntax of the Input string is invalid, or the specified 
time Is out of range. 



NOTES 



1 For absolute time, the input string must be formatted as 

dd-mmm-yy)^ hh:mm:ss.cc 

For absolute time, any of the fields may be omitted, but all punctuation 
must be included. The system will fill in the current values for all 
unspecified fields. 

Examples are: 

a. 5-DEC-1983 5:16:14.98 (16 minutes, 14.98 seconds after 5 A.M. on 
5-DEC-1983) 

b. - 14:00:00.00 (2 P.M. today) 

c. - ::05 (5 seconds past the current time) 
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MACRO-32 
EXAMPLE 



2 For relative time (time offset from the current time), the input string 
format is 

dddd hh:mm:ss.cc 

For relative time, any of the fields may be omitted, but all punctuation 
must be included. The system will default all unspecified fields to 0. 

Examples are: 

a. 4 12:46:14.56 (4 days, 12 hours, 46 minutes, 14.56 seconds from 
now) 

b. 5:12 (5 hours and 12 minutes from now) 

c. ::10 (10 seconds from now) 



ONE_MIN! .ASCID /O 00:01:00.00/ ;DESCRIPTOR FOR 1 MINUTE. 

BIN TIM .BLKQ 1 ;QUADWORD TO HOLD BINARY TIME. 



$BINTIM_S ONE_MIN, BIN_TIM 



BLISS-32 
EXAMPLE 



BIND 

ONE MIN 



UPLIT (%ASCID '0 00:01:00.00'); ! DESCRIPTOR FOR 1 MINUTE. 

LOCAL 

BIN_TIM : VECTOR [2]; ! QUADWORD TO HOLD BINARY TIME. 



$BINTIM (TIMBUF=.ONE_MIN, TIMADR=BIN_TIM) ; 
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$DS_BITDEF 



The $DS_BITDEF macro defines (for MACRO-32 programs) a bit masl< for 
each bit from through 31 . For BLISS-32 programs, these symbols may 
be referenced without first issuing the $DS_BITDEF macro. 

Symbols defined are: 

BITO = 00000001 (HEX) 
BITl = 00000002 (HEX) 
BIT2 = 00000004 (HEX) 



BIT31 = 80000000 (HEX) 



MACRO-32 $DS_BITDEF [gblj 



ARGUMENTS gbl 

Can be LOCAL or GLOBAL 



MACRO-32 
EXAMPLE 

$DS BITDEF GLOBAL 
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$DS_BNCOMPLETE 



The $DS_BCOMPLETE and $DS_BNCOMPLETE program control macros 
can be used to test the return status of a system service (or any routine 
which returns a status code in RO) and branch if the service's operation 
was "complete" or "incomplete." 



MACRO-32 $DS_BNCOIVIPLETE adr 



BLISS-32 



Not supported for BLISS-32, since testing RO is implicit in the language. 
See the example below. 



ARGUMENTS adr 

Address to branch to if tested condition is satisfied. 



NOTES 



For all error status codes, bit is clear. Therefore, this macro simply 
generates the following code: 

$DS_BNCOMPLETE - BLBC RO,adr 

If an error status code is detected, the contents of RO should be 
compared with all error codes that could possibly be returned from 
the service (or other) routine to determine the exact nature of the error. 



MACRO-32 
EXAMPLE 

$DS_GETBUF #2, RETADDR, PHYSADDR 
$DS BNCOMPLETE BAD_BUF 



BLISS-32 
EXAMPLE 

IF $DS_GETBUF (PAGCNT=2) THEN 
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$DS_BNERROR 



The $DS_BERROR and $DS_BNERROR program control macros can be 
used to test the return status of a system service (or any routine which 
returns a status code in RO) and branch if the service's operation was in 
error or was error-free. 



MACRO-32 



$DS_BNERROR adr 



BLISS-32 



Not supported for BLISS-32, since testing RO is implicit in the language. 
See the example below. 



ARGUMENTS adr 



Address to branch to if tested condition is satisfied. 



NOTES 



1 For all error status codes, bit is clear. Therefore, this macro simply 
generates the following code: 



$DS BNERROR 



BLBS RO,adr 

2 If an error status code is detected, the contents of RO should be 
compared with all error codes that could possibly be returned from 
the service (or other) routine to determine the exact nature of the error. 



MACRO-32 
EXAMPLE 

$DS_GPHARD LOG_UNIT, ADDRl 
$DS_BNERROR 10$ 



BLISS-32 
EXAMPLE 

IF NOT $DS_GPHARD (UNIT=.LOG_UNIT, RETADR=ADDR1 ) THEN 
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SDS^BNOPER 



The $DS_BNOPER macro can be used to determine the presence of 
an operator (user) during program execution. (The presence of a user 
is indicated by the condition of the VDS control flag OPERATOR.) This 
macro can be used to control whether certain portions of the program are 
executed only if a user is present. $DS_BNOPER will cause a branch if 
the operator flag is clear. 



MACRO-32 



$DS_BNOPER adr 



BLISS-32 



Not implemented for BLISS-32. Direct reference of the corresporiding VDS 
control flag, as illustrated in the example below, is recommended. 



ARGUMENTS adr 



Address to which to branch if the tested condition is satisfied. 



MACRO-32 
EXAMPLE 

$DS_BNOPER 100$ 



BLISS-32 
EXAMPLE 



IF .DSA$V OPER THEN BEGIN 



END; 
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$DS_BNPASSO 



The $DS_BNPASSO program control macro can be used within the 
initialization code to determine if the current pass through the initialization 
code is the first one. It is often necessary to perform certain operations 
the first time the initialization code is executed that should not be repeated 
on subsequent passes through the initialization code, such as initialization 
of run-time variables. (It is helpful to think of "pass 0" as the execution 
that takes place before the first pass through the tests occurs.) 

$DS_BNPASSO will cause a branch if the current pass through the 
initialization code is not the first one. This macro may only be used in 
the initialization code. 



MACRO-32 



$DS_BNPASSO adr 



BLiSS-32 



Not implemiented for BLISS-32. Direct reference of the corresponding VDS 
control flag, as illustrated in the example below, is recommended. 



ARGUMENTS adr 



Address to branch to if the tested condition is satisfied. 



MACRO-32 
EXAMPLE 



$DS_BNPASSO 50$ 



BLISS-32 
EXAMPLE 



IF .DSA$V PASSO THEN BEGIN 



END; 
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$DS_BNQUICK 



The $DS_BNQUICK program control macro can be used to determine 
if the VDS control flag QUICK has been set by the program user. The 
$DS_BNQUICK will cause a branch if the QUICK flag is clear. If the flag 
has been set, the diagnostic program should execute only the portions of 
code deemed appropriate to the "quick" mode of operation. 



MACRO-32 



$DS^BNQUICK adr 



BLISS-32 



Not implemented for BLISS-32. Direct reference of the corresponding VDS 
control flag, as illustrated in the example below, is recommended. 



ARGUMENTS adr 



Address to which to branch if the tested condition is satisfied. 



MACRO-32 
EXAMPLE 

$DS BNQUICK 100$ 



BLISS-32 
EXAMPLE 



IF .DSA$V_ QUICK THEN BEGIN 



END; 
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$DS_BOOTATTACHED 



In a multiprocessing environment, use the Boot Attached CPU system 
service to bootstrap an attached processor on a multiprocessor system. It 
will perform the following functions for the target processor: 

1 Halt the processor, if it is not currently halted. 

2 Perform all initialization necessary to enable the processor to execute 
code, including Initializing stacks, memory management registers, the 
SCB, and the interval clock. 

3 Cause the processor to enter the idle state (see Figure 4-8). 

After you call the $DS_BOOTATTACHED, use the $DS_STARTATTACHED 
sen/ice to cause the attached processor to leave the idle state and begin 
executing a section of code while in the running state. 



MACRO-32 



$DS_BOOTATTACHED_x unit, scb_addr 



BLISS-32 



$DS_BOOTATTACHED (UNIT = unit, 

SCB_ADDR = scb_addr); 



ARGUMENTS unit 



Logical unit number of the processor to be bootstrapped. 

scb_addr 

Address of the longword to receive the SCB address of the target 
processor. 



RETURN 
STATUS 



DS$_NORMAL 
DS$JLLUNIT 
DSSJNVCPU 
DS$_MEM_ALLOC_ERR 

DS$_INITFAIL 



Service successfully completed. 

The specified logical unit number Is too large. 

Cannot boot specified processor. 

Could not allocate memory for attached processor's 
SCB and stacks. 

Attached processor failed Initialization. 
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MACRO-32 
EXAMPLE 

$DS_BOOTATTACHED_S LOG_UNIT, PR0C2_SCB 



BLlSS-32 
EXAMPLE 

$DS BOOTATTACHED (UNIT = .LOG_ONIT, SCB_ADDR = PR0C2_SCB); 
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$DS^BOPER 



The $DS_BOPER macro can be used to determine the presence of an 
operator (user) during program execution. (The presence of a user is 
indicated by the condition of the VDS control flag OPERATOR.) This 
macro can be used to control whether certain portions of the program are 
executed only if a user is present. $DS_BOPER will cause a branch if the 
OPERATOR flag is set. 



MACRO-32 



$DS_BOPER adr 



BLISS-32 



Not implemented for BLISS-32. Direct reference of the corresponding VDS 
control flag, as illustrated in the example below, is recommended. 



ARGUMENTS adr 



Address to which to branch if the tested condition is satisfied. 



IVIACRO-32 
EXAMPLE 

$DS_BOPER 100$ 



BLISS-32 
EXAMPLE 



IF .DSA$V OPER THEN BEGIN 



END; 
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$DS^BPASSO 



The $DS_BPASSO program control macro can be used within the 
initialization code to determine if the current pass through the initialization 
code is the first one. It is often necessary to perform certain operations 
the first time the initialization code is executed that should not be repeated 
on subsequent passes through the initialization code, such as initialization 
of run-time variables. (It is helpful to think of "pass 0" as the execution 
that takes place before the first pass through the tests occurs.) 

$DS_BPASSO will cause a branch if the current pass through the 
initialization code is the first one. This macro may only be used in the 
initialization code. 



MACRO-32 



$DS_BPASSO adr 



BLISS-32 



Not implemented for BLISS-32. Direct referer\ce of the corresponding VDS 
control flag, as illustrated in the example below, is recommended. 



ARGUMENTS adr 



Address to branch to if the tested condition is satisfied. 



MACRO-32 
EXAMPLE 

$DS BPASSO PASSl 



BLISS-32 
EXAMPLE 



IF .DSA$V_PASSO THEN BEGIN ... END; 
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$DS_BQUICK 



The $DS_BQUICK program control macro can be used to determine if 
thie VDS control flag QUICK lias been set by the program user. The 
$DS_BQUICK will cause a branch if the QUICK flag is set. If the flag has 
been set, the diagnostic program should execute only the portions of code 
deemed appropriate to the "quick" mode of operation. 



MACRO-32 



$DS_BQUICK adr 



BLISS-32 



Not implemented for BLISS-32. Direct reference of the corresponding VDS 
control flag, as illustrated in the example below, is recommended. 



ARGUMENTS adr 



Address to which to branch if the tested condition is satisfied. 



MACRO-32 
EXAMPLE 



$DS BQUICK TAGl 



BLISS-32 
EXAMPLE 



IF .DSA$V QUICK THEN BEGIN 



END; 
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$DS_BREAK 



The Break system service causes a temporary return to the VDS to take 
place. The main purpose of this return is to see if any asynchronous 
events including receipt of a control-C character from the user terminal) 
have occurred and are waiting to be processed. 

All diagnostic programs must return to the VDS at least once every three 
seconds. Issuing any system service macro or program control macro, plus 
some program structure macros (such as $DS_ENDSUB and $DS_ENDTEST), 
is considered to be a return to the VDS, so the $DS_BREAK sen/ice only 
needs to be called if none of those macros has been issued in a particular 
3-second interval. Be particularly careful that all potential program loops 
(see Section 3. 10) adhere to this constraint. 

In a multiprocessor environment, code executing in attached processors 
must also call $DS_BREAK periodically. 



MACRO-32 



$DS_BREAK (No suffix.) 



BLISS-32 



$DS_BREAK; 



RETURN 
STATUS 



None. 



MACRO-32 
EXAMPLE 

$DS BREAK 



BLISS-32 
EXAMPLE 

$DS_BREAK; 
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$CANCEL 



The Cancel I/O on Channel system service can be used to cancel I/O 
requests that were created with the $QIO and $QIOW system services. 
The caller specifies the number of the channel for which I/O requests are 
to be canceled, and the service will cancel all current and pending I/O 
operations directed to the channel. 

Level 3 programs may not use this service. 



MACRO-32 



$CANCEL_x Chan 



BLISS-32 



$CANCEL (CHAN = Chan); 



ARGUMENTS 



Chan 

Number of the I/O channel on which I/O is to be canceled. 



RETURN 
STATUS 



SS$_NORMAL 
SS$_EXQUOTA 

SS$JNSFMEM 

SS$JVCHAN 

SS$_NOPRIV 



Service successfully completed. 

Tlie process lias exceeded its direct I/O quota. 
User mode only. 

Insufficient memory space is available to perform the 
Cancel I/O service. 

An invalid channel number was specified; that is, a 
chiannel number of or a number larger than the 
number of channels available. 

The specified channel was not assigned, or was 
assigned from a more privileged access mode. User 
mode only. 



NOTES 



1 See the VAX/VMS System Services Reference Manual for discussions of 
privilege restrictions, resource requirements, and other notes relating to 
the $CANCEL service. 
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MACRO-32 
EXAMPLE 

^CANCEL S CHANNUM 



BLISS-32 
EXAMPLE 

$CANCEL (CHAN=. CHANNUM) 



5-69 



$CANTIM 



$CANTIM 



The Cancel Timer Request system service can be used to cancel timer 
requests previously made with the $SETIMR macro. See Section 4.4.4, 
Timing. 



MACRO-32 



$CANTIM_x [reqidt], [acmode] 



BLISS-32 



$CANTIM ([REQIDT = reqidt], [ACMODE = acmode]); 



ARGUMENTS 



reqidt 

The request identification number of the timer request to be canceled. A 
request id number is associated with each timer request when the $SETIMR 
macro is used. The $CANTIM service will only cancel the requests having 
the specified id number. The default value is 0, ivhich means that all timer 
requests should be canceled, regardless of their id numbers. 

acmode (user mode only) 

Access mode of the requests to be canceled. In user inode, the access 
mode is maximized with the access mode of the caller. Only those timer 
requests issued from an access mode equal to or less privileged than the 
resultant access mode are canceled. 



RETURN 
STATUS 



SS$_NORMAL 



Servicfe successfully completed. 



MACRO-32 
EXAMPLE 

$CANTIM_S #2 ; Cancel timer request(s) with ID of 2. 



BLISS-32 
EXAMPLE 



$CANTIM ( ) ; 



ICancel all timer requests. 
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$DS„CANWAIT 



The Cancel Wait system service is used to cancel a program wait state 
that was created by using the $DS_WAITMS or $DS_WAITUS macro. See 
Section 4.4.4, Timing. 



MACRO-32 



$DS_CANWAIT_x 



BLISS-32 



$DS_CANWAIT; 



RETURN 
STATUS 



SS$_NORMAL 



Service successfully completed. 



NOTES 



The $DS_CANWAIT macro is only useful if it is included in an AST 
routine or interrupt service routine that was entered while a $DS_WAITMS 
or $DS_WAITUS service was being executed. See Section 4.4.4. 



MACRO-32 
EXAMPLE 

$DS CANWAIT_S 



BLISS-32 
EXAMPLE 

$DS CANWAII; 
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$DS_$CASE 



The $DS_$CASE p-table descriptor macro is used to test the current 
contents of the "value register" (see Section 3.2.3.3) and then load a new 
value into the register, depending on the old contents. The $DS_$CASE 
macro is used to specify pairs of values. The current value register 
contents are compared with the first value of each pair until a match is 
found; the second value of the pair is then loaded into the value register. 
There may be any number of pairs in the case list. If no pair matches the 
value register, then the value register is not altered. 



MACRO-32 



$DS_$CASE <<case_pair>, [<case_pair>, ...]> 



BLISS-32 



$DS_$CASE ((casejDair), [(casej)air), ...J); 



ARGUMENTS case_pair 

A pair of values, separated by a comma. Each value will be stored in a 
longword. 



NOTES 



Code generated by macro (shown in Macro-32; Bliss-32 is equivalent): 



.BYTE -^XSC ; Beginning of CASE 

.BYTE n ; Number of case pairs 

.LONG matchl, valuel ; First case pair 

; Other case pairs 

.LONG match-n, value-n; Last (nth) case pair 



MACRO-32 
EXAMPLE 

$DS_$CASE < - 

<1,2>, - 
<2,3>, - 
<3,4» 

$DS_$CASE «1 , <"XFFFFF» , <2 , <'^XFFFEFFFF»> 
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BLISS-32 
EXAMPLE 

$DS_$CASE ( 

(1,2), 
(2,3), 
(3,4))! 

$DS_$CASE ( ( 1 , %X ' FFFFF ' ) , ( 2 , %X ' FFFEFFFF ' ) ) ; 



5-73 



$DS_CFDEF 



$DS__CFDEF 



The $DS_CFDEF macro defines (for MACRO-32 programs) symbolic 
names for tlie fields of a call frame. For BLISS-32 programs, these 
symbols may be referenced without first issuing the $DS_CFDEF macro. 

Symbols defined are: 

CF$L_ONCOND - Address of condition handler 



CF$W_PSW 


- Processor status word 


CF$W_MASK 


- Register mask 


CF$L_AP 


- Saved AP 


CF$L_FP 


- Saved FP 


CF$L_PC 


- Saved PC 


CF$L_REG 


- Start of saved RO through Rll 



NOTES 



These sjnnbols are used as offsets from the current FP, as in 
CF$W_PSW(FP). 



MACRO-32 



$DS_CFDEF [gbl] 



ARGUMENTS gbl 



Can be LOCAL or GLOBAL 



MACRO-32 
EXAMPLE 

$DS CFDEF GLOBAL 
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$DS_CHANNEL 



The VDS Channel Adapter system service controls functions that are 
initiated by referencing internal registers in the bus adapters. This service 
takes into account all processor-specific differences in the adapters and 
thus insulates the diagnostic program from those differences. 

The Channel Adapter service enables the program to: 

Initialize a MASSBUS adapter, a UNIBUS adapter, or a UNIBUS-like 
VAXBI adapter, such as the KDB50. 

Initialize a UNIBUS 

Enable and disable interrupts from an adapter 

Abort data transfers on a MASSBUS adapter 

Purge a UNIBUS data path 

Set or clear UNIBUS defeat parity 

Request or clear adapter status 

Run self-test on a VAXBI adapter 

Stop a VAXBI adapter from issuing any more VAXBI transactions 

For descriptions of the design and operation of the various bus adapters 
for VAX processors, refer to the VAX Hardware Handbook. 

The Channel Adapter system service may only be used by level 3 
diagnostic programs. 



IVIACRO-32 $DS_CHANNEL_x unit, func, [vecadr], [stsadr], [time], 

[bistsadr] 



BLISS-32 



$DS_CHANNEL (UNIT= unit, FUNC = func, 

[VECADR = vecadr], 
[STSADR = stsadr], [TIME = time], 
[BISTSADR = bistsadr]); 
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ARGUMENTS unit 



Logical unit number of the device unit to be tested. The function specified 
by "func" is performed on the adapter to which this device unit is 
attached. 

func 

Function code indicating the function to be performed by the 
$DS_CHANNEL service. Must be a literal value. In MACRO-32, function 
codes are defined by the $DS_CHCDEF macro. Note 1 describes function 
codes. 

vecadr 

Address of interrupt service routine to receive control when an interrupt 
occurs. The interrupt may come from the device specified by "unit" or 
from the adapter to which the device is attached. This parameter is only 
used with the CHC$_ENINT function code, in which case it is required. 

stsadr 

Address of a quadword to receive adapter status. Used only with the 
CHC$_ENINT and CHC$_STATUS function codes, in which cases it is 
required. Note 2 discusses adapter status. 

time 

The number of ten-millisecond time units to wait for the VAXBI node self- 
test to complete. Used only with the CHS$_SELF_TEST and CHC$_IN1TA 
functions codes and only when referencing VAXBI nodes. 

bistsadr 

Address of a quadword to receive the contents of the BIIC CSR and the 
BUG BER registers. Used only with the CHC$_STATUS and CHC$_ENINT 
function codes and only when referencing VAXBI adapters. 



RETURN 
STATUS 



DS$_NORMAL 

DS$_ERROR 

DS$_IHWE 



DS$JWECT 



DS$_LOGIC 



DS$_NOSUPPORT 



Service successfully completed. 

The specified logical unit number is too large. 

Initial hardware error. An error condition detected 
in the adapter is preventing the function from being 
performed. To determine the exact hardware error, 
issue a CHC$_STATUS function. 

The p-table for the device unit indicated with the 
"unit" parameter contains an invalid vector address. 

An attempt to set or clear a bit within an adapter 
register has failed. Indicates a hardware failure. 

The specified function is not supported on the 
processor type being used. This is not an error 
condition. See Note 4. 
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DS$_PROGERR An invalid function code was specified. 

A required argument was not included witti the macro 
call. 

DS$_BIIC BIIC self-test failed. 

DS$_NODE VAXBI node self-test failed. (BIIC self-test 

succeeded.) 



I^QJ gg 1. Function Codes 

Following is a list of valid function codes with their functions and return 
status codes: 

• CHC$_INITA - Initialize the MASSBUS, UNIBUS, or VAXBI adapter 
to which the device unit specified by "unit" is attached. For VAXBI 
nodes, self-test is invoked and "time" may be specified. See Note 6. 

Return status codes: DS$_NORMAL, DS$_ERROR, DS$_LOGIC, 
DS$_NOSUPPORT, DS$_BIIC, DS$_NODE 

• CHC$_INITB — Initialize the UNIBUS to which the device unit 
specified by "unit" is attached. 

Rehirn stahis codes: DS$_NORMAL, DS$_ERROR, DS$_LOGIC, 
DS$_NOSUPPORT 

• CHC$_ENINT - Enable interrupts for the MASSBUS, UNIBUS, or 
VAXBI adapter to which the device unit specified by "unit" is attached. 
Refer to Note 3 for details. 

Return status codes: DS$_NORMAL, DS$_ERROR, DS$_IHWE, 
DS$_IVVECT, DS$_LOGIC, DS$_PROGERR 

• CHC$_DSINT - Disable interrupts for the MASSBUS, UNIBUS, or 
VAXBf adapter to which the device unit specified by "unit" is attached. 

Reharn status codes: DS$_NORMAL, DS$_ERROR, DS$_IHWE, 
DS$_IWECT, DS$_LOGIC 

• CHC$_ ABORT — Abort data transfers on the MASSBUS adapter to 
which the device unit specified by "unit" is attached. 

Rehim status codes: DS$_NORMAL, DS$_ERROR, DS$_NOSUPPORT 

• CHC$_PURGE — Purge a buffered data path on a UNIBUS. The 
buffered data path that is purged is the one specified by the last 
DS$_SETMAP macro call. The UNIBUS will be the one to which the 
device unit specified by "unit" is attached. 

Return stahis codes: DS$_NORMAL, DS$_ERROR, DS$_NOSUPPORT 

• CHC$_CLEAR — Clear status bits. Clears error bits in the stahis 
registers of the adapter to which the device unit specified by "unit" 
is attached. This function should be requested before interrupts are 
enabled. 

Return status codes: DS$_NORMAL, DS$_ERROR, DS$_LOGIC, 
DS$_NOSUPPORT 
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• CHC$_STATUS — Fetch status for the adapter to which the device 
unit specified by "unit" is attached. The current status of the adapter 
will be returned in the quadword specified by "stsadr." For status 
definitions, see Status-1 Fields and Status-2 Fields located in Note 2. 

Return status codes: DS$_NORMAL, DS$_ERROR 

• CHC$_SETDFT - Sets the Defeat Data Path Parity bit for the UNIBUS 
adapter to which the device unit specified by "unit" is attached. 

Return status codes: DS$_NORMAL, DS$_ERROR, DS$_NOSUPPORT 

• CHC$_CLRDFT - Clears the Defeat Data Path Parity bit for the 
UNIBUS adapter to which the device unit specified by "unit" is 
attached. 

Return stahis codes: DS$_NORMAL, DS$_ERROR, DS$_NOSUPPORT 

• CHC$_SELF_TEST - Initiates self-test in the specified VAXBI node, 
waiting either the amount of time specified by the time parameter or 
ten seconds if time is not specified. (See Note 6 for exceptions to the 
ten-second default value.) 

Reharn status codes: DS$_NORMAL, DS$ ERROR, DS$ BIIC, 
DS$_NODE 

• CHC$_STOP — Stops a VAXBI node from issuing VAXBI transactions. 
Return status codes: DS$_NORMAL, DS$_ERROR, DS$_LOGIC 

2. Adapter Status 

Adapter status is returned to the caller either when the CHC$_ STATUS 
function is requested or when an interrupt occurs. 

In the latter case, the interrupt service routine (whose address was 
specified with the "vecadr" parameter) can (and should) examine the 
status quadword to see if errors have occurred. 

The returned status quadword has the format shown in Figure 5-4. 

Figure 5-4 Adapter Status Format 



31 




16 


15 





STATUS-1 


VECTOR 


STATUS-2 



Note: Both longwords are filled when an interrupt occurs. If the CHC$_STATUS 
function is requested, however, only the first longword is filled in; the 
second longword is cleared. 
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Status-l Field 

Status-1 is a 4-byte bitmap, with eacti bit representing an error 
condition. Each bit has a sjmibolic name in the form CHS$V_xxxxx 
and a longword mask in the form CHS$M_xxxxxx. In MACRO'32, 
these symbols are defined by the $DS_CHSDEF macro. 

Status-1 bits are defined as follows. Unless noted, these bits also apply 
to VAXBI systems. 

Bit - CHS$V_SYSERR — System error. Set if either of bits 9 or 10 is 
set. 

Bit 1 - CHS$V_CHNERR - Channel error. Set if any of bits 6, 7, 8, 
25, 26, and 27 are set. 

Bit 2 - CHS$V_DEVERR — Device error. Set if either of bits 4 or 5 is 
set. 

Bit 3 — CHS$V_PGMERR - Program error. Set if bit 11 is set. 

Bits 0, 1, 2, and 3 — CHS$M_ERRANY (defined only as longword 
mask) — Can be used to test if any error conditions of types SYSERR, 
CHNERR, DEVERR, or PGMERR exist. 

Bit 4 - CHS$V_DEVBUS — Bus error. Some type of error has 
occurred on the bus. 

Bit 5 — CHS$V_DEVTO — Device timeout. The referenced device did 
not respond. 

Bit 6 - CHS$V_CHNDPE - Data path parity error. 

Bit 7 - CHS$V_CHNMPE - Map parity error. A MASSBUS page 
frame map parity error or a UNIBUS map register parity failure was 
detected. 

Bit 8 - CHS$V_CHPFOT - Power failure/Overtemp. A power failure 
or overtemperature condition was detected. 

Bit 9 - CHS$V_SYSMEM — System memory error. Set if any of a 
number of error conditions relating to data transfers was detected. 

Bit 10 — CHS$V_SYSSBI — SBI error. For processors having an SBI, 
this bit is set if an SBI error condition is detected. 

Bit 11 — CHS$V_PGMHDE — Hardware-detected program error. The 
mapping registers were not set up correctly by the software, or the 
software attempted to initiate a MASSBUS data transfer while one was 
already in progress. 

Bits 12 through 15 — Unused. 

Bit 16 - CHS$V_MBAEXC - MASSBUS exception. 

Bit 17 - CHS$V_MBANED - Nonexistent MASSBUS device. The 
referenced MASSBUS device did not respond. Equivalent to bit 5. 

Bit 18 - CHS$V_MBADTB - MASSBUS DTBUSY. Set if MASSBUS 
DTBUSY is set (not an error bit). 

Bit 19 - CHS$V_MBADTC — MASSBUS data transfer completed. Set 
if MASSBUS DT CMP is set. 
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Bit 20 - CHS$V_MBAATN - MASSBUS attention. Set if MASSBUS 
ATTN is set. 

Bit 21 — CHS$V_MBACPE — MASSBUS control parity error. Set if 
MASSBUS MCPE is set. 

Bit 22 - CHS$V_BUSINIT - UNIBUS INIT asserted. Set if UB INIT 
is set. 

Bit 23 — CHS$V_BUSIC — UNIBUS initialization completed. Set if 
UBIC is set. 

Bit 24 - CHS$V_BUSPDN - UNIBUS power down. Set if UB PDN is 
set. 

Bit 25 - CHS$V_MBAWCKLWR - MASSBUS write check lower error. 
Set if MASSBUS WCK LWR ERR is set. 

Bit 26 - CHS$V_MBAWCKUPR - MASSBUS write check upper error. 
Set if MASSBUS WCK UP ERR is set. 

Bit 27 — CHS$V_BUSNXM — UNIBUS nonexistent memory or device. 
The referenced address does not respond. 

Bit 28 - CHS$V_UIE - UNIBUS Interlock Error; set if a DATO(B) 
does not follow a DATIP transaction on the UNIBUS. 

Bit 29 — CHS$V_BADBDP — Bad Buffered Data Path; set if data path 6 
or 7 is selected. 

Bit 30 — CHS$V_BADPAR — Set if RAM parity error occurred. 

Note: Whenever the status-1 field shows an error, the program should call 
the $DS_SHOWCHAN service to display the bus adapter's internal 
registers on your terminal so that you can determine the exact cause of 
the error. 

• Status-2 Field 

Status-2 is a 2-byte bitmap that is returned for interrupts only. Each 
bit has a symbolic name in the form CHI$V_xxxxx and a mask in the 
form CHI$M_xxxxxx. In macro-32, these symbols are defined in the 
$DS_CHIDEF macro. 

Status-2 bits are defined as follows: 

Bit — CHI$V_CHNINT — Set if the adapter issues the interrupt. 

Bit 1 — CHI$V_DEVINT - Set if the device issues the interrupt. 

Bits 2-6 - CHI$V_IPL — (five-bit field starting at bit position 
CHI$V_IPL and having a length defined by CHI$S_IPL) Contains 
the interrupt priority level (IPL) of the interrupt. 

Note: CHI$V_CHNINT and CHI$V_DEVINT are not mutually exclusive; that 
is, both a device interrupt and an adapter interrupt can occur at the 
same time. 
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Vector Field 

The 2-b3rte vector field contains the vector address of the UNIBUS 
device that caused the interrupt. 

Bits 16-31 — CHI$V_RVR — Receive vector register. 

Additional Status for VAXBI Nodes 

If you specify the "bistsadr" argument with the CHC$_STATUS or 
CHC$_ENINT hinctions, contents of the BHC CSR and BI BER are 
returned. 

BIIC CSR contents are loaded into the first longword of the quadward 
specified by bistsadr. Each bit has a symbolic name in the form 
BIIC$V_. Unless noted, a mask is also defined in the form BIIC$M_. 
In macro-32, these sjnnbols are defined by the $BIICDEF macro. 

BIIC CSR bits are defined as follows: 

Bits to 3 - BIIC$V_NODE_ID - Node ID. (Note about 
BnC$S_NODE_ID) 

Bits 4 to 5 - BnC$V_ARBCNTL - Arbitration mode. (Note about 
BIIC$S_ARBCNTL) 

Bit 6 - BIIC$V_SEIE - Soft error interrupt enable. 

Bit 7 - BIIC$V_HEIE — Hard error interrupt enable. 

Bit 8 - BIIC$V_UWP - Unlock write pending. 

Bit 10 - BIIC$V_SST - Start self-test. 

Bit 11 - BIIC$V_STS - Self-test status. 

Bit 12 - BIIC$V_BROKE - Broken. 

Bit 13 - BIIC$V_INIT - Initialization. 

Bit 14 - BIIC$V_SES - Soft error summary. 

Bit 15 - BIIC$V_HES - Hard error summary. 

Bits 16-23 - BIIC$V_BIICTYPE - BIIC interface type. (Note about 
BIIC$S_TYPE.) 

Bits 24-31 - BIIC$V_BnCREVN - BIIC interface revision (Note about 
BIIC$S_BIICREVN.) 

BIIC BER contents are loaded into the second longword of the 
quadword specified by bistsadr. Each bit has a symbolic name in 
the form BIIC$V_. A mask is also defined in the form BIIC$M_. In 
macro-32, these symbols are defined by the $BIICDEF macro. 

BIIC BER bits are defined as follows: 

Bit - BIIC$V_NPE - Null bus parity error. 

Bit 1 - BIIC$V_CRD - Corrected read data. 

Bit 2 - BnC$V_IPE - ID parity error. 

Bit 3 - BIIC$V_UPEN - User parity enable. 

Bit 16 - BIIC$V_ICE - Illegal confirmation error. 

5-81 



$DS_CHANNEL 



Bit 17 — BIIC$V_NEX — Non-existent address. 

Bit 18 - BIIC$V_BTP — Bus timeout. 

Bit 19 — BIIC$V_STO — Stall timeout. 

Bit 20 - BIIC$V_RTO - Retry timeout. 

Bit 21 - BIIC$V_RDS - Read data substitute. 

Bit 22 - BnC$V_SPE - Slave parity error. 

Bit 23 — BIIC$V_CPE — Command parity error. 

Bit 24 — BIIC$V_IVE — Indent vector error. 

Bit 25 — BIIC$V_TDF — Transmitter during fault. 

Bit 26 — BIIC$V_ISE — Interlock sequence error. 

Bit 27 — BIIC$V_MPE - Master parity error. 

Bit 28 — BIIC$V_CTE - Control transmit error. 

Bit 29 — BIIC$V_MTCE — Master loopback error. 

Bit 30 — BIIC$V_NMR — NOACK to multi-responder command 
received. 

3. Interrupts 

The CHC$_ENINT function enables interrupts for the adapter provided 
the adapter is capable of generating interrupts. Device interrupts must be 
explicitly enabled by the diagnostic program. The CHC$_ENINT function 
loads the appropriate vector addresses and MUST be used, even if the 
adapter, itself, cannot generate interrupts. 

Device vector addresses are loaded with the address of an interrupt 
preprocessor within the VDS. When an interrupt occurs, program control is 
vectored to the interrupt preprocessor. 

The interrupt preprocessor: 

• Raises the processor's IPL to 17 (hex) 

• Check for errors incurred by the bus adapter 

• Constructs the status quadword 

• Determines the type of interrupt: adapter, device, or "passive release." 

If the interrupt is from an adapter- or a device, the appropriate bit in 
the status-2 field is set and control is passed to the user's interrupt service 
routine ("vecadr") with a JMP instruction. If a passive release has occurred, 
an REI instruction is executed without calling the diagnostic program's 
interrupt service routine. 

The diagnostic program's interrupt service routine should compare the 
vector in the status quadword with the vector in HP$W_ VECTOR of 
the interrupting device's p-table to ensure that the interrupt is from the 
expected device. 
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It is not wise to request the CHC$_INITA or CHC$_INITB function while 
interrupts are enabled as it may result in an undefined hardware state in 
some devices. 

4. Processor-Specific Considerations 

Some functions are not relevant for certain processors. For example, the 
CHC$_INITB is not relevant on a VAX-1 1/730 but, in order to allow a 
diagnostic program to be compatible with all processor types, the VDS 
does not reject the function. It rehirns the DS$_NOSUPPORT stahis code. 
In this case, you should consider a the DS$_NOSUPPORT a success status, 
since the low bit of the status code is set. 

5. Multiprocessor Note 

• $DS_ CHANNEL must be called by the primary processor. It cannot be 
called by code executing in an attached processor. 

6. CHC$_INITA function with VAXBI adapters 

• The only VAXBI adapters for which the CHC$_INITA function may 
be used are the BUA, the BLA, and the KDB50. For these adapters, 
self-test is invoked. The "time" argument can be used with self-test. If 
time is not specified, the default value is 100 milliseconds for the BUA, 
200 milliseconds for the BLA, and 10 seconds for the KDB50. 



MACRO-32 
EXAMPLE 



Following is an example in MACRO-32 and BLISS-32 of code that initializes 
a MASSBUS, enables bus interrupts, and issues a SEARCH function on an 
RP06 disk drive. 



20$: 



$DS_CHANNEL_S - 

DRIVE, #CHC$_INITA 
$DS_SETIPL_S #0 
MOVL NEXT_ADDR , RPDA ( R2 ) 
MOVL CYLINDER, RPDC(R2) 
$DS_CHANNEL_S - 

DRIVE, #CHC$_ENINT, 
CLRQ CH_STATUS 
MOVL # SEARCH ! GO , ( R2 ) 
BBC #CHS$V_MBAATN, - 

CH_STATUS, 20S 
BITL #ERR,RPDS(R2) 



Initialize MASSBUS 

Lower I PL 

Next disk address to access. 
Desired cylinder. 
Enable interrupts. 
SERVICE_RTN, CH_STATUS 

Clear status quadword. 

SEARCH function. 

Wait for SEARCH to finish. 

Check for drive errors . 
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BLISS-32 
EXAMPLE 



$DS_CHANNEL 

(UNIT = .DRIVE, 
FUNC = CHC$_INITA) ; 

$DS_SETIPL (0); 

.(RP_BASE + RPDA) = .NEXT_ADDR; 

.(RP_BASE + RPDC) = .CYLINDER; 

$DS_CHANNEL 

UNIT = .DRIVE, 
FUNC = CHCS_ENIT, 
VECADR = SERVICE_RTN, 
STSADR = CH_STATUS; 

CH_STATUS = 0; 

.(RP_BASE + RPCS) = SEARCH OR GO; 

REPEAT 

1 
UNTIL .CH_STATUS <CHSSV MBAATN, 1>; 
IF .(RP_BASE + RPDS) <ERR, 1> 
THEN . . . 
ELSE ... ; 



Initialize MASSBUS 



Lower I PL 

Next disk address to access. 

Desired cylinder. 

Enable interrupts. 



! Clear status quadword. 

! SEARCH function. 

! Wait for SEARCH to finish. 



If drive errors occurred 
then . . . 
else . . . 
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$DS_CHCDEF 



The $DS_CHCDEF macro defines (for MACRO-32 programs) the symbolic 
names of the function codes associated with the $DS_CHANNEL service. 
For BLISS-32 programs, these symbols may be referenced without first 
issuing the $DS_CHCDEF macro. 

Symbols defined are: 

chc$_inita 

chc$_initb 

chc$_enint 

chc$3dsint 

chc$2abort 

chc$~purge 

chc$~clear 

chc$~status 

chc$~setdft 

chc$_clrdft 

chc$_self_test 

CHC$ STOP 



MACRO-32 $DS_CHCDEF [gblj 



ARGUMENTS gbl 

Can be LOCAL or GLOBAL 



MACRO-32 
EXAMPLE 

$DS CHCDEF GLOBAL 
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$DS_CHMDEF 



The $DS_CHMDEF macro defines (for MACRO-32 programs) symbolic 
names of the function codes associated with the $DS_SETI\/1AP service. 
For BLISS-32 programs, these symbols may be referenced without first 
issuing the $DS_CHI\/IDEF macro. 

Symbols defined are: 

CHM$_INVALIDATE 

CHM$_MFWDN 

CHM$_MFWDNO 

CHM$_MFWDV 

CHM$_MPWDVO 

CHM$_MREVN 

CHMS_MREVNO 

CHM$-MREW 

CHM$-MREVVO 
CHM$_NFWDN 
CHM$ NREVN 



MACRO-32 SDS^CHMDEF [gbl] 



ARGUMENTS qbl 

Can be LOCAL or GLOBAL 



MACRO-32 
EXAMPLE 

SDS CHCDEF GLOBAL 
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$DS_CHSDEF 



The $DS_CHSDEF macro defines (for MACRO-32 programs) symbolic 
names for tiie STATUS-1 bits associated with the $DS_CHANNEL service. 
For BLISS-32 programs, these symbols may be referenced without first 
issuing the $DS_CHSDEF macro. 

Symbols defined are: 



CHS$M 


SYSERR 


CHS$M 


CHNERR 


CHS$M 


DEVERR 


CHS$M 


PGMERR 


CHS$M 


DEVBUS 


CHS$M 


DEVTO 


CHS$M 


CHNDPE 


CHS$M 


CHNMPE 


CHS$M 


CHPFOT 


CHS$M 


SYSMEM 


CHS$M 


SYSSBI 


CHS$M 


PGMHDE 


CHS$M_MBAEXC 


CHS$M 


MBANED 


CHS$M 


MBADTB 


CHS$iyi 


MBADTC 


CHS$M 


MBAATN 


CHS$M 


MBACPE 


CHS$M 


BUSINIT 


CHS$M. 


BUSIC 


CHS$M 


BUSPDN 


CHS$M 


MBAWCLKWR 


CHS$M 


MBAWCKUPR 


CHS$M 


BUSNXM 


CHS$M 


UIE 


CHS$M 


BADBDP 


CHS$M. 


BADPAR 



MACRO-32 



$DS_CHSDEF [gbl] 



ARGUMENTS gbl 

Can be LOCAL or GLOBAL 



MACRO-32 
EXAMPLE 

$DS CHSDEF GLOBAL 
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$DS^CKLOOP 



The $DS_CKLOOP program control macro is used to explicitly specify 
the upper bound of a program loop. It is used when the implicit upper 
bound provided by a $DS_ENDSUB macro creates a loop that is not 
useful. A detailed discussion of program looping, including the use of the 
$DS_CKLOOP macro, is provided in Section 3.10, Looping. 



MACRO-32 



$DS^CKLOOP label 



BLISS-32 



Not supported for BLISS-32. See Note 2. 



ARGUMENTS 



label 

Address of loop's lower bound. After the $DS_CKLOOP is executed, 
program flow branches to this address. The address must be lower than 
the location of the $DS_CKLOOP macro, but higher than the most recent 
$DS_BGNTEST or $DS_BGNSUB macro. 



NOTES 



If $DS_CKLOOP macros are used in a test that does not contain 
subtests, the $DS_CKLOOP macros may be placed anywhere within 
the test. For tests that contain subtests, the $DS_CKLOOP macros must 
be placed within the subtests. 

The $DS_CKLOOP has not been implemented for BLISS-32. However, 
programs written in BLISS-32 (and MACRO-32, for that matter) 
can define sufficiently small program loops with judicious use of 
$DS_BGNSUB and $DS_ENDSUB macros. 

The $DS_INLOOP system service may be used inside the bounds of a 
loop to determine whether or not the loop is actually being executed. 



5-88 



$DS_CKLOOP 



EXAMPLES 



$DS BGNSUB 



LOOP BGN: 



$DS ERRHARD UNIT=LOG_UNIT, MSGADR-HRDl, PRLINK=HRDRTN1 



$DS_CKLOOP LOOP_BGN 



$DS_ENDSUB 
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$DS_CLI 



The $DS_CLI program structure macro is used to create a parse tree. The 
tree can then be used to parse command strings containing commands 
defined by the diagnostic program (see Section 4.2.2.2, Prompting the 
User). Actual parsing of a command string can be performed by the 
$DS_PARSE system service. That service wili traverse a parse tree 
previously constructed with the $DS_CLI macro. 

A parse tree is created by using a set of $DS_CLI macros. Each time the 
macro is used, a node of the tree is created. IViost nodes will possess the 
following: 

• A character, string of characters, or special "traversal code" that will 
indicate what must be next in the input command string to constitute a 
legal command. 

• An "action code" that will be passed to an "action routine" if there is 
a match between the tree node and the input command string. Action 
routines are detailed in the discussion of the $DS_PARSE macro. 

• The address of a node to jump to if the current traversal path turns out 
to be the wrong one {a mismatch has been encountered). 

Once the tree has been created, the $DS_PARSE system service can 
be used. That service will start at the root of the tree and traverse it, 
comparing an input command string with the characters or "traversal 
codes" contained in each node. Each time there is a match, the 
$DS_PARSE service will call the "action routine," passing to the routine 
the "action code" specified with the $DS_CLI macro. Then the next 
node in the current path will be checked. If, on the other hand, there Is a 
mismatch, the system service will jump to the node specified as being the 
one to go to on a mismatch. 



MACRO-32 



$DS_CLI char, action, miss, [ascii] 



BLISS-32 



Not implemented for BLISS-32. 



ARGUMENTS char 



• A character to be compared to the next character in the input string, or 

• A "traversal code," indicating which types of characters should be 
expected next in the input string. The traversal codes are defined by 
the $DS_CLIDEF macro. They are discussed in Note 1. 

action 

Code to be passed to the action routine. The action routine is called every 
time there is a match between the current node and the input string. 
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miss 

Address of node to jump to if there is a mismatch at the current node. 

ascll 

ASCn string to be used as node content if CLI$K_STRING is used for 
"char" (see Note 1). See examples for proper format. 

I^QYgg The "char" parameter may either be a single ASCII character or it may be a 

traversal code. Its purpose is to indicate to the $DS_PARSE system service 
what character, characters, or t3^es of characters should be expected next 
in the input string. The traversal codes are defined by the $DS_CLIDEF 
macro. The actions that the $DS_PARSE service will take for each traversal 
code are defined as follows: 

• CLI$K_ALNUM — Continue reading input string as long as alphabetic 
or numeric characters are encountered. 



• 



CLI$K_ ALPHA — Continue reading input string as long as alphabetic 
characters are encountered. 



• CLI$K_NUM — Continue reading input string as long as numeric 
cheiracters are encountered. Numeric characters must be valid for the 
current default radix setting (refer to the SET DEFAULT command in 
the VAXJDS Diagnostic Supervisor User's Guide.) 

• CLI$K_SYMBOL — Continue reading input string as long as valid 
symbol characters are encovmtered. Valid s5nnbol characters are A-Z, 
0-9, $, and _. 

• CLI$K_FILE — Continue reading input string as long as valid filename 
characters are encountered. (Filename characters are A-Z, 0-9, plus 
the wildcard characters * and %.) 

• CLI$K_SPACE — Continue reading input string as long as spaces are 
encountered. If no spaces exist at the current point in the input string, 
do not call the action routine; branch to "miss" instead. 

• CLI$K_COMMA — Find next nonspace input character, and see if it 
is a comma. If so, find next nonspace input character, then call action 
routine. Otherwise branch to "miss." 

• CLI$K_SLASH — Find next nonspace input character, and see if it is 
a slash (/). If so, find next nonspace input character, then call action 
routine. Otherwise branch to "miss." 

• CLI$K_ VALUE — Find next nonspace input character, and see if it is 
a : or an = . If so, find next nonspace input character, then call action 
routine. Otherwise branch to "miss." 

• CLI$K_EOL — Find next nonspace input character, and see if it is a 
line terminator. If so, call action routine. Otherwise branch to "miss." 

• CLI$K_DEC — Continue reading input string as long as valid decimal 
numeric characters are encountered. 

• CLI$K_HEX — Continue reading input string as long as valid 
hexadecimal numeric characters are encountered. 
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CLI$K_OCT — Continue reading input string as long as valid octal 
numeric characters are encountered. 

CLI$K_STRING — Continue reading input string as long as the input 
string matches the character string specified by the "ascii" parameter. 
The comparison is considered to be a match even if only the first 
character of the input string (starting at the current pointer position) 
matches the character string. 

CLI$K_BR — Call the action routine, then branch unconditionally to 
the address specified by "miss." No reading of the input string occurs. 

CL1$K_BIF — Call the action routine, then branch to address specified 
by "miss" if bit of RO is set. No reading of the input string occurs. 

CLI$K_CALL — Call action routine, then unconditionally branch to 
another parse tree. Address of tree is specified by "miss." Do not 
nest calls. 

CLI$K_RETURN — Call action routine, then return to original parse 
tree, to the $DS_CLI macro directly following the macro containing 
the CLI$K_CALL code. The action routine may set or clear bit of 
RO. The contents of RO will then be saved for use by the CLI$K_BIFS 
macro. 

CLI$K_BIFS — Used after return from a subtree. Call action routine, 
then branch if the action routine had set bit of RO during processing 
of CU$K_RETURN macro. (Contents of RO will have aheady 
changed, but its value will have been saved during processing of 
CLI$K_RETURN.) 

CLI$K_EXIT — Call the action routine, then stop traversing the tree. 
The $DS_PARSE system service returns control to the caller, with RO 
set to SS$_NORMAL. No reading of the input string occurs. This code 
is used to indicate that the input string has been successfully parsed. 

CLI$K_ERROR — Call the action routine, then stop traversing the tree. 
The $DS_PARSE system service returns control to the caller, with RO 
set to DS$_ERROR. No reading of the input string occurs. This code 
is used to indicate an unsuccessful parse of the input string (an illegal 
command string was specified). 
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EXAMPLES 



Here is a simple but instructive example of a user-defined command 
language. Suppose we wanted to create a command language to represent 
some of the steps involved in baking a cake. Consider just the following 
steps: 

1 Add sugar. 

2 Add salt. 

3 Add milk. 

4 Beat ingredients. 

5 Bake cake. 

Figure 5-5 illustrates a parse tree for this command language. 
Figure 5-5 Sample Parse Tree 
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This tree would be described with $DS_CLI macros as follows: 



NO_ACTION=0 

ADD=1 

BAKE=2 

BEAT=3 

MILK=4 

SALT=5 

SUGAR=6 

ILLCMD=7 

BADARG=8 

TREE_ROOT : : 

$DS_CLI CLI$K_SPACE, NO_ACTION, ADD_NODE 

ADD_NODE: 

$DS_CLI CLI$K_STRING, ADD, B_NODE, 'ADD' 

$DS_CLI CLI$K_SPACE, NO_ACTION, ILLCMD$ 

$DS_CLI CLI$K_STRING, MILK, S_NODE, 'MILK' 

$DS_CLI CLISK_E0L, NO_ACTION,~BADARG$ 

$DS~CLI CLI$K_EXIT 



B NODE: 



$DS_CLI <'^A'B'>, NO_ACTION, ILLCMD$ 
$DS_CLI CLI$K_STRING, BAKE, EAT_NODE, 'AKE' 
$DS~CLI CLI$K~EOL, NO_ACTION, ILLCMD$ 
$DS CLI CLI$K EXIT 



EAT_NODB : 

$DS_CLI 
$DS_CLI 
$DS~CLI 

S_NODE : 

$DS_CLI 
$DS_CLI 
$DS_CLI 
$DS_CLI 

UGAR_NODE : 

$DS_CLI 
$DS_CLI 
$DS~CLI 



CLI$K_STRING, BEAT, ILLCMD$, 'EAT' 
CLI$K_EOL, NO_ACTION, ILLCMD$ 
CLI$K_EXIT 



<^A'S'>, NO_ACTION, ILLCMD$ 
CLI$K_STRING, SALT, UGAR_NODE, 'ALT' 
CLI$K_EOL, NO_ACTI0N, BADARG$ 
CLI$K EXIT 



CLI$K_STRING, SUGAR, BADARG$, 'UGAR' 
CLI$K_EOL, NO_ACTION, BADARG$ 
CLI$K_EXIT 



; Leading spaces 

;ADD 

;ADD<space> 

;ADD<space>MILK 

; ADD<space>MI LK<cr> 



B 

BAKE 

BAKE<cr> 



;BEAT 
;BEAT<cr> 



;ADD<space>S 

;ADD<space>SALT 

;ADD<space>SALT<cr> 



;ADD<space> SUGAR 

; ADD<spac e>SUGAR<cr > 



DONE! 



ILLCMD$: 



BADARG$ I 



$DS_CLI CLI$K_EXIT 

$DS_CLI CLI$K_ERROR, ILLCMD 

$DS_CLI CLI$K_ERROR, BADARG 
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$DS^CLIDEF 



The $DS_CLIDEF macro defines (for MACRO-32 programs) symbolic 
names for the "traversal codes" used in associated with the $DS_CLI 
macro. 

Symbols defined are: 



CLI$K 


ALNUM 


CLI$K 


ALPHA 


CLI$K 


NUM 


CLI$K 


SYMBOL 


CLI$K 


FILE 


CLI$K 


SPACE 


CLI$K 


COMMA 


CLI$K 


SLASH 


CLISK 


VALUE 


CLI$K 


EOL 


CLI$K 


DEC 


CLI$K 


HEX 


CLI$K 


OCT 


CLI$K 


STRING 


CLI$K 


BR 


CLI$K 


BIF 


CLI$K 


CALL 


CLI$K 


RETURN 


CLI$K 


BIFS 


CLI$K 


EXIT 


CLISK 


ERROR 



MACRO-32 



$DS_CLIDEF [gbl] 



ARGUMENTS gbl 

Can be LOCAL or GLOBAL 



MACRO-32 
EXAMPLE 

$DS CLIDEF GLOBAL 
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$CLOSE 



The Close File service of RMS is used to close a file after all processing 
of the file has been completed. The $CLOSE service will also perform a 
$DISCONNECT operation. 



MACRO-32 



$CLOSE fab, [err], [sue] 



BLrSS-32 



$CLOSE (FAB = fab, [ERR = err], [SUC = sue]); 



ARGUMENTS rab 



RETURN 
STATUS 



Address of the RAB to be associated with the FAB describing the file to 
which connection is to be made. (The address of the FAB is in the RAB.) 

err (user mode only) 

Address of a routine to be executed on error return from the service. 

SUC (user mode only) 

Address of a routine to be executed on successful return from the service. 



RMS$_NORMAL 
RMS$_CCF 



Service successfully completed. 

Cannot close file. (Status value will be placed in 
STV of FAB.) 



Note: For further details on return status values, refer to the VAX-11 RMS 
Reference Manual. 
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NOTES 



Table 5-1 lists the FAB fields used by the $CLOSE service IN 
STANDALONE MODE. For user mode, refer to the VAX-ll RMS Reference 
Manual. 



MACRO-32 
EXAMPLE 

$CLOSE FAB_ADDR 



Table 5-1 FAB Fields Used by $CLOSE (Standalone Mode) 



Field Mnemonic 



Field Name 



Input: 

IFI 

XAB 

Output: 

IFI 

STS 

STV 



Internal file Identifier. 

Extended attribute block address. 

Internal file Identifier (zeroed). 

Completion status code (also returned in RO). 

Status value. 



BLISS-32 
EXAMPLE 

$CLOSE (FAB=FAB_ADDR); 
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$CLREF 



The $CLREF macro is used to clear event flags. (Event flags are 
discussed in Section 4.4.2). 



MACRO-32 



$CLREF_x efn 



BLISS-32 



$CLREF (EFN = efn); 



ARGUMENTS efn 



Number of the event flag to be cleared. In user mode, the number may be 
from 1 through 23, or from 32 through 127. In standalone mode, flags 1 
through 64 may be used. 



RETURN 
STATUS 



SS$_WASCLR 

SS$_WASSET 

SS$JLLEFC 
SS$_UNASEFC 



Service successfully completed. The specified flag 
was previously 0. 

Service successfully completed. Ttie specified flag 
was previously 1 . 

An illegal event flag number was specified. 

In user mode, indicates that the specified common 
event flag (see Section 4.4.2 has not been 
associated with the process issuing the CLREF 
macro. 

In standalone mode, indicates that an event flag 
from 64 through 127 was specified. These flags are 
not valid in standalone mode. 



MACRO-32 
EXAMPLE 

$CLREF S #5 



; Clear event flag 5. 



BLISS-32 
EXAMPLE 

$CLREF (EFN-5); 



! Clear event flag 5. 
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$DS_CLRVEC 



The Clear Exception or Interrupt Vector system service is used to load 
an exception or interrupt vector with the address of the standard VDS 
condition handler for the specified vector. The macro's purpose is 
to restore the standard VDS vector contents after the vector has been 
modified with the $DS_SETVEC service. 

Only level 3 diagnostic programs may use the $DS_CLRVEC macro. 



MACRO-32 



$DS_CLRVEC_x vector 



BLiSS-32 



$DS_CLRVEC (VECTOR = vector); 



ARGUMENTS vector 

The vector address, relative to the base of the System Control Block (SCB). 



RETURN 
STATUS 



DS$_NORMAL 
DS$_IWECT 



Service successfully completed. 

Address specified for "vector" is not a valid vector 
address. 



MACRO-32 
EXAMPLE 



$DS CLRVEC S #"X60 



; Restore VDS handler address for 
; memory write timeout vector 



BLISS-32 
EXAMPLE 



S DS_CLRVEC ( %X ' 6 ' ) ) 



! Restore VDS handler address for 
! memory write timeout vector 



5-99 



$DS_CNTRLC 



$DS_CNTRLC 



The Declare Control-C Handler system service has two purposes. It can 
be used to: 

• Declare a control-C handler that will receive control when the program 
user types a control-C 

• Enable and disable delivery of control-Cs 

Refer to Section 4.4.6, Handling Control-Cs, for a details on control-C 
handlers and disabling delivery of control-Cs. 

If the $DS_CNTRLC service is not used, the VDS control-C handler will be 
invoked. 



MACRO-32 



$DS_CNTRLC_x [astadr], [disabi] 



BLISS-32 



$DS_CNTRLC ([ASTADR = astadr], 

[DISABL = disable]); 



ARGUMENTS 



astadr 

Address of the control-C handler. Default value is 0, which causes VDS 
control-C handler to be declared. 

disable 

Value used to indicate if control-C delivery should be disabled or enabled. 
If disable is set to 1, control-C delivery will be disabled. If the value is 
(the default), control-C delivery is enabled, and control-Cs will be delivered 
to whichever control-C handler has been selected. 



RETURN 
STATUS 



SS$_WASSET 



SS$_WASCLR 



Service successfully completed. Control-C delivery 
was previously disabled (the disable flag was 
previously set). 

Service successfully completed. Control-C delivery 
was previously enabled (the disable flag was 
previously clear). 



5-100 



$DS_CNTRLC 



MACRO-32 
EXAMPLES 

$DS_CNTRLC_S CNTRLC_HDLR ;I want to handle control-Cs. 
$D5_CNTRLC S fLet VDS handle control-Cs. 

$DS CNTRLC_S DISABL=# 1 .-Disable control-Cs. 



BLISS-32 
EXAMPLES 

$DS_CNTRLC (ASTADR=CNTRLC_HDLR) ; !I want to handle control-Cs 
$DS_CNTRLC (); !Let VDS handle control-Cs. 

$DS_CNTRLC (DISABLE=1); ! Disable control-Cs. 
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$DS_$COMPLEMENT 



This p-table descriptor macro complements the current contents of the 
value register. 



MACRO-32 $DS_$COMPLEMENT 



BLISS-32 



$DS_$COIWPLEMENT: 



NOTES 



Code generated by macro (shown in Macro-32; Bliss-32 is equivalent): 
.BYTE 0(89 ; Complement value register 
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The Connect RAB to FAB service of RMS is used to associate an RAB 
to an FAB after the file described In the FAB has been opened with the 
$OPEN service. The file cannot be read until after It has been connected. 



MACRO-32 



$CONNECT rab, [err], [sue] 



BLISS-32 



$CON N ECT (RAB = rab, [ERR = err], [SUC = sue]); 



ARGUMENTS rab 



RETURN 
STATUS 



Address of the RAB to be associated with the FAB describing the file to 
which connection is to be made. (The address of the FAB is in the RAB.) 

err (user mode only) 

Address of a routine to be executed on error return from the service. 

Stic (user mode only) 

Address of a routine to be executed on successful return from the service. 



RMS$_NORMAL 
RMS$_CCR 

RMS$_FAB 
RMSSJFI 
RMS$_RAB 
RMS$_RAC 



Service successfully completed. 

An RAB is already associated witli the specified 
FAB. 

The FAB blocl< is invalid. 

The FAB's IFI field is invalid. 

The RAB block is invalid. 

Invalid record access mode. In standalone mode, 
only sequential and RFA access modes are allowed. 



Note: For further details on return status values, refer to the VAX-11 RMS 

Reference Manual. 
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NOTES 



Table 5-2 lists the RAB fields used by the $CONNECT service IN 
STANDALONE MODE. For user mode, refer to the VAX-11 RMS Reference 

Manual. 



MACRO-32 
EXAMPLE 

$CONNECT RAB ADDR 



Table 5-2 RAB Fields Used by $CONNECT (Standalone Mode) 



Field Mnemonic 



Field Name 



Input: 

FAB 
ROP 
Output: 

SIS 



Address of FAB. 

Record-processing options. (Only BIO is allowed.) 

Completion status code. (Also returned in RO.) 



BLISS-32 
EXAMPLE 

$CONNECT ( RAB=RAB_ADDR ) ; 
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The Convert Register Contents to Character String system service can be 
used to produce an ASCiC character string that associates each field in a 
register (or any iongword) with a mnemonic and indicates the current value 
of each field. When the string is constructed, the following algorithm is 
used: 

• For fields consisting of only one bit, the field mnemonic is placed into 
the output string only if the bit is set. 

• For fields greater than one bit in length, two options are available: 

— A mnemonic can be associated with the field, in which case the 
mnemonic and the field's numeric value (in the specified radix) are 
placed Into the output string. 

— Instead of associating a mnemonic with the field, the field's 
VALUE can have a mnemonic assigned to it. In this case, only 
the mnemonic is placed into the output string. 

The string can be displayed on the user terminal by using one of the 
$DS_PRINTx services. 



IViACRO-32 



$DS CVTREG_x msb, data, mneadr, strbuf, maxlen, 

[v1], [v2J. [v3], Ml [v5], [v6] 



BLISS-32 



$DS_CVTREG (MSB = msb, DATA = data, 

MNEADR = mneadr, STRBUF = strbuf, 
MAXLEN = maxlen, [V1 = v1], [V2 = v2], 
[V3 = v3J, [V4 = v4J, [V5 = v5], [V6 = v6J); 



ARGUMENTS 



msb 

Most significant bit. Reading of the specified location's fields progresses 
from left to right, so this parameter indicates the first bit that is to be read. 
Maximum value is 31. 

data 

Contents to be converted. (Note that this is not the address of the contents, 
but the contents themselves.) 

mneadr 

Address of a string of mnemonics and field specifiers. 

A mnemonic may be a string of any length, containing any character except 
' = ', ',', or '©'. 
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Fields are specified in the following manner; 

• For one-bit fields, simply include the mnemonic and follow it by a 
comma, such as ...,MNEM1,MNEM2,MNEM3,... 

• For multiple-bit fields, two formats are used: 

— If a mnemonic is to be associated with the field, the format is 
"mnemonic = size"radix", where "size" is the size of the field and 
"radix" is the radix in which the field contents is to be displayed. 
Valid values for "radix" are "X" (hexadecimal), "O" (octal), and 
"D" (decimal). An example is IPL = 50(. 

— If a mnemonic is to be associated with the field's VALUE, the 
format is "mnemonic = size®", where "size" is the size of the 
field. The value's mnemonic is specified using the "vl" through 
"v6" parameters. 

• If a bit is not to be included in any field, simply include a comma in 
the mnemonics list; for example, ...,BIT10,BIT9,,,BIT6,... 

• The first mnemonic in the list will be associated with the bit indicated 
by the "msb" parameter. Mnemonics will be assigned from left to 
right until the mnemonics list has been exhausted, or until bit has 
been reached, whichever happens first. 

strbuf 

Address of a buffer to receive the character string. 

maxlen 

Length of the buffer pointed to by "strbuf." The buffer may not be greater 
than 255 bytes. Caution: If the character string overruns the specified 
length, the buffer will not contain a valid string. 

v1 through v6 

Each of these, if used, is the address of a coimted table of value 
mnemonics. Each table will contain pointers to lists of mnemonics that 
are to be associated with the possible values for a particular field. One of 
these tables will be referenced each time a field specifier with the format 
"mnemonic = size®" is encountered in the mnemonic string (pointed to by 
"mneadr"). The first time that format is used, the table pointed to by "vl" 
will be referenced; the second time the format is used, the table pointed to 
by "v2" will be referenced, and so on. 

Each entry in a table will be the address of a mnemonic that is to be 
associated with the field's value. The value contained in the field will be 
used as an offset into the table. If the field's value is 0, the first table entry 
will be fetched; if the field's value is 1, the table's second entry will be 
used, and so on. The mnemonic pointed to by the table entry must be 
defined by an ASCIC string. The mnemonic will be placed into the output 
string. Figure 5-6 illustrates the linkages involved in this mechanism. 



5-106 



$DS_CVTREG 



RETURN 
STATUS 



DS$_NORMAL 
DS$_PROGERR 



Service successfully completed. 

The output string was too large to fit into the buffer 
provided, or was larger than 255 characters. 

The string of mnemonics and field descriptors 
contains an Invalid field descriptor. 

The value specified for "msb" was greater than 31 . 

The total number of macro arguments was greater 
than 11. 



Figure 5-6 $DS_CVTREG Value Mnemonics Table Usage 



VI: 



ADDRESS OF 
TABLE_T1 



V2: 



ADDRESS OF 
TABLE_T2 



TABLE T1: 



N 


T1. 


_ADDR. 


_1 


T1. 


.ADDR. 


.2 


^ ^ 
^ *• 


T1. 


.ADDR. 


" 



T1_ADDR_1: .ASCIC yT1_STRING_1/ 
T1_ADDR_2: .ASCIC /T1_STR1NG_2/ 



TABLE_T2: 



N 


T2. 


.ADDR. 


.1 


T2_ 


_ADDR_ 


_2 


, ; 


T2_ 


.ADDR. 


" 



T2_ADDR_1: .ASCIC /T2_STRING_1/ 
T2_ADDR_2: .ASCIC /T2_STRING 2/ 



T2_ADDR_N: .ASCIC /T3_STRING_N/ 

ZK 4795-85 
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NOTES 



On return from the service, Rl will contain the total length of the 
output string, even if the string overflowed. 

A good convention to follow is to not leave any fields unlabeled. Fields 
that must be zero (MBZ), are not used, or consist of "don't care" bits 
should be identified as such. This will cause the fields to be read and 
displayed, and the program user will know if, for example, an MBZ bit 
actually is 0. 



IVIACRO-32 
EXAMPLE 



PSL NME: 



The following examples illustrate, in both MACRO-32 and BLISS-32, a 
method of displa)dng the processor's PSL. 

.ASCIC /CM,TP,MBZ=2'^X,FPD,IS,CUR=2e,PRV=2e,MBZ,/ - 
/IPL=5'>X,MBZ=8-'X,DV,FU,IV,T,N,Z,V,C/ 



MODE_LIST: 




.LONG 


4 








•ADDRESS KERNEL 








.ADDRESS EXEC 








.ADDRESS SUPER 








.ADDRESS USER 


KERNEL: 






.ASCIC 


/KERNEL/ 


EXEC: 






.ASCIC 


/EXECUTIVE/ 


SUPER: 






.ASCIC 


/SUPERVISOR/ 


USER: 






.ASCIC 


/USER/ 


OUT_BUF 


: 




.BLKB 


255 




MOVPSL 


RO 






$DS. 


.CVTREG - 










MSB 


= #31, - 








DATA 


= RO, - 








MNEADR 


= PSL_MNE, - 








STRBUF 


= OUT BUF, - 








MAXLEN 


= #255, - 








VI 


^ MODE_LIST, - 








V2 


= MODE LIST 



; Fetch PSL contents. 

; Create string. 

;Read all 32 bits. 

;PSL contents. 

; Mnemonics string. 

;Output buffer. 

; Maximum length. 

;lst table. 

;2nd table (use 1st one again). 
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$DS_CVTREG 



BLISS-32 
EXAMPLE 



BIND 



BIND 



OWN 
OWN 

BUILTIN 
LOCAL 



PSL_MNE = 
UPLIT 
(%ASCIC 

'CM,TP,MBZ=2'^X,FPD,IS,COR=2e,PRV=2@,MBZ,IPL=5'^X,MBZ=8'X, 
DV,FO,IV,T,N,Z,V,C' ) ; 

KERNEL = UPLIT (%ASCIC 'KERNEL'), 

EXEC = UPLIT (%ASCIC 'EXECUTIVE'), 

SUPER = UPLIT (%ASCIC 'SUPERVISOR'), 

USER = UPLIT (%ASCIC 'USER' ) ; 

HODE_LIST S VECTOR [5] INITIAL (4, KERNEL, EXEC, SUPER, USER); 

OUT_BUF ; VECTOR [255, BYTE]; 

MOVPSL; 



PSL_STORE; 



MOVPSL ( PSL_STORE ) ; 

$DS_CVTREG 

(MSB = 31, 

DATA = .PSL_STORE, 

MNEADR = PSL_MNE, 

STRBUF = OUT_BUF, 

MAXLEN =255, 

VI = MODE_LIST, 

V2 = MODE_LIST); 



! Fetch PSL contents. 

! Create string. 

SRead all 32 bits. 

!PSL contents. 

! Mnemonics string. 

! Output buffer. 

IMaxlength. 

•1st table. 

!2nd table (use 1st one again) 
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$DASSIGN 



The Deassign I/O Channel system service of VMS is used to release an I/O 
channel that was previously assigned with the $ASSIGN service. Level 2R 
diagnostic programs should use this macro when all I/O operations on a 
device have been completed. See Section 4.2.1.1 for details of I/O in user 
mode. 



MACRO-32 



$DASSGN X Chan 



BLISS-32 



$DASSGN (CHAN = chan); 



RETURN 
STATUS 



SS$_NORMAL 
SS$_IVCHAN 

SS$_NOPRIV 



Service successfully completed. 

An invalid channel number was specified; that is, a 
channel number of or a number larger than the 
number of channels available. 

The specified channel is not assigned, or was 
assigned from a more privileged access mode. 



NOTES 



See the VAX/VMS System Sewices Reference Manual for notes on the 
SDASSGN macro. That manual should be read before performing I/O 
operations in user mode. 



MACRO-32 
EXAMPLE 

$DASSGN 8 CHAN NUM 



BLISS-32 
EXAMPLE 

$DASSGN ( CHAN= . CHAN_NUM ) ; 
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$DS_$DECIMAL 



$DS^$DECIMAL 



This p-table descriptor macro reads a value from the ATTACH command 
iine. If no more parameters are available on the command line, or if the 
next parameter is not a decimal value, it will prompt the operator with the 
prompt text value. The value that is read is stored in the "value register" 
(see Section 3.2.3.3) for use by a $DS_$COMPLEMENT, $DS_$STORE, or 
$DS_$CASE statement. 



MACRO-32 $DS_$DECIMAL <prompt>, low, high 



BLISS-32 



$DS_$DECIMAL (PROMPT = 'prompt', LOW = low, 

HIGH = high); 



ARGUMENTS 



prompt 

Character string that is to be printed as a prompt to the user. This prompt 
will be used if the ATTACH command line does not contain the required 
value. 

low 

The low limit for the value. If the value given is lower than this, an error 
message followed by the prompt message will be displayed. The default 
radix for this value is decimal. 

high 

The high limit for the value. If the value given is higher than this, an error 
message followed by the prompt message will be displayed. The default 
radix for this value is decimal. 



NOTES 



Code generated by macro (shown in Macro-32; Bliss-32 is equivalent): 



.BYTE '>X82 

.ASCIC \prompt\ 

.LONG low 

. LONG high 



Beginning of DECIMAL prompt 
Prompt string 
Low limit 
High limit 
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$DS_$DECilVIAL 



MACRO-32 
EXAMPLE 



$DS_$DECIMRL TR, 1, 15 

$DS $DECIMRL PROMPT=<NUMBER OF ARRAY CARDS>, LOW=0, HIGH=15 



BLlSS-32 
EXAMPLE 

$DS_$DECIMRL ( PROMPT= ' TR ' , L0W=1, HIGH=15); 

SDS_SDECIMAL ( PROMPT= ' NUMBER OF ARRAY CARDS', LOW=0, HIGH=15); 
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$DEF 



The $DEF macro, defined in tiie VI\/IS system library STARLET.MLB, Is 
used to define a field in a data structure, sucli as p-tabie descriptors, as 
discussed in Section 3.2.2. 

$DEF is only defined between calls to $DEFINi and $DEFEND. 



MACRO-32 $DEF sym, alloc, siz 



BLISS-32 



Not supported for BLISS-32. 



ARGUMENTS 



sym 

Symbolic name to be associated with the field. 

alloc 

Allocation unit. Use one of the MACRO-32 block storage directives for this 
parameter. MACRO-32 block storage directives are of the form ".BLKx," 
such as .BLKW or .BLKQ. 

Siz 

Size of the field. This indicates the number of allocation units to assign. 



EXAMPLE 



$DEF FIELDl, .BLKL, 1 ;Field named FIELDl is 1 longword. 
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$DS_DEFDEL 



$DS^DEFDEL 



The $DS_DEFDEL macro is used to conserve memory space during 
program assembly time. Some of tiie symbol definition macros cause 
memory space to be allocated. If the $DS_DEFDEL macro is issued 
AFTER the symbol definition macros, then any memory space allocated 
during the symbol definition process will be deallocated. This will not 
affect the symbol definitions themselves. 
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$DEFEND 



$DEFEND— $DEFINI 



The $DEFEND and $DEFINI macros, defined in tlie VMS iibrary 
STARLET. IVI LB, are used to define data structures, such as p-table 
descriptors, as discussed in Section 3.2.2. (Use the $DEF macro to 
define the fieids within the data structure, itself.) 



MACRO-32 



$DEF1NI struc, gbl, dot 

(data structure field definitions) 
$DEFEND struc, gbl, suf 



BLISS-32 



Not supported for BLISS-32. 



ARGUMENTS 



struc 

S3mibolic name for stucture being defined by the $DEFINI macro. 

gbl 

GLOBAL or LOCAL. Indicates whether the data structure's symbolic name 
("struc") will be defined globally or locally. 

dot 

Address of the first field within the data structure. The symbol defined by 
the first $DEF macro will be assigned to this value. Subsequent fields are 
assigned to the next sequential memory addresses. The argument can be 
numeric (for example, 512), or symbolic (for example, BLOCK_ADDR). If 
symbolic, the symbol must be defined before the IdEFINI macro call. The 
default is 0. 

suf 

Structure name suffix. The default is "DEF". 



EXAMPLE 

SDEFINI TABLEl, GLOBAL, OFFSET 
$DEF FIELDl, .BLKL, 2 
SDEF FIELD2, .BLKB, 1 

S DEFEND TABLEl, GLOBAL 

In this example, a global data structure named "TABLEl" has been defined 
to contain two fields, called FIELDl and FIELD2. FIELDl starts at location 
TABLEl + OFFSET and consists of 2 longwords. FIELD2 immediately 
follows FIELDl and is one bjrte long. 
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$DEFINI— $DEFEND 



The $DEFINI and $DEFEND macros, defined in the VMS library 
STAR LET. MLB, are used to define data structures, such as p-table 
descriptors, as discussed in Section 3.2.2. (Use the $DEF macro to 
define the fields within the data structure, itself.) 



MACRO-32 



$DEFINI struc, gbl, dot 

(data structure field definitions) 
$DEFEND struc, gbl, suf 



BLISS-32 



Not supported for BLISS-32. 



ARGUMENTS 



struc 

Symbolic name for stucture being defined by the $DEFINI macro. 

gbl 

GLOBAL or LOCAL. Indicates whether the data structure's symbolic name 
("struc") will be defined globally or locally. 

dot 

Address of the first field within the data structure. The symbol defined by 
the first $DEF macro will be assigned to this value. Subsequent fields are 
assigned to the next sequential memory addresses. The argument can be 
numeric (for example, 512), or sjnnbolic (for example, BLOCK_ADDR). If 
S3mibolic, the symbol must be defined before the $DEFINI macro call. The 
default is 0. 



suf 

Structvire name suffix. 



The default is "DEF". 



EXAMPLE 



$DEFINI TABLEl, GLOBAL, OFFSET 

$DEF FIELDl, .BLKL, 2 

$DEF FIELD2, .BLKB, 1 

$DEFEND TABLEl, GLOBAL 



In this example, a global data structure named "TABLEl" has been defined 
to contain two fields, called FIELDl and FIELD2. FIELDl starts at location 
TABLEl + OFFSET and consists of 2 longwords. FIELD2 immediately 
follows FIELDl and is one b)rte long. 
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SDS^DEVTYP 



The $DS_DEVTYP macro is used to indicate to the VDS which types of 
devices the diagnostic program is capable of testing. 



MACRO-32 



$DS_DEVTYP < [string], [string],... >, 

< [address], [address], ...> 



BLISS-32 



$DS_DEVTYP ([STRINGS = < string, [string], . . 
[ADDRESSES = < address, 
[address],... >]); 



■ >],) 



ARGUMENTS 



string 

Character string representing a device type, such as 'RK06' or 'TM03'. This 
parameter is used to specify device types for which p-table descriptors 
exist in the VDS. 

address 

Address of a p-table descriptor defined within the diagnostic program. 
P-table desciptors must be defined within the diagnostic program if: 

1 A p-table descriptor for the device does not exist in the VDS, or 

2 The programmer wishes to override the VDS's p-table descriptor for a 
device. P-table descriptors are discussed in Section 3.2.2. 



MACRO-32 
EXAMPLE 

$DS_DEVTYP <RP04, RP05, RP06> 
$DS_DEVTYP <>,<DESCR1, DESCR2> 



BLiSS-32 
EXAMPLE 

$DS_DEVTYP (STRINGS=<RP04, RP05, RP06>); 
$D5_DEVTYP (ADDRESSE5=<DESCR1, DESCR2>); 
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$DISCONNECT 



The Disconnect RAB from FAB service of RMS is used to breai< the 
connection between an RAB and an FAB. This terminates the record 
stream and deallocates all I/O buffers and data structures. 



MACRO-32 



$DISCONNECT rab, [err], [sue] 



BLISS-32 



$DISCONNECT (RAB = rab, [ERR = err], [SUC = sue]); 



ARGUMENTS rab 



RETURN 
STATUS 



Address of the RAB to be disconnected. (The RAB will contain the address 
of its associated FAB.) 

err (user mode only) 

Address of a routine to be executed on error return from the service. 

SUC (user mode only) 

Address of a routine to be executed on successful return from the service. 



RMS$_NORMAL 

RMS$JFI 

RMS$_ISI 

RMS$_FAB 
RMS$_RAB 



Service successfully completed. 

The FAB's IFI field is Invalid. 

Invalid stream id. Tlie specified RAB and FAB were 
not connected. 

The FAB block Is invalid. 

The RAB block Is Invalid. 



Note: For further details on return status values, refer to the VAX-11 RMS 
Reference Manual. 
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$DISCONNECT 



NOTES 



Table 5-3 lists the RAB fields used by the $DISCONNECT service IN 
STANDALONE MODE. For user mode, refer to the VAX-11 RMS Reference 
Manual. 



Table 5-3 RAB Fields Used by $DISCONNECT (Standalone Mode) 



Field Mnemonic 


Field Name 


input: 




ISI 


Internal stream identifier. 


Output: 




STS 


Completion status code. 




(Also returned in RO.) 



MACRO-32 
EXAMPLE 

$DISCONNECT RAB_ADDR 



BLISS-32 
EXAMPLE 

$DI SCONNECT ( RAB=E?AB_ADDR ) ; 
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$DS^DISPATCH 



The $DS_DISPATCH macro generates the diagnostic program "dispatch 
table." This table contains the starting addresses of all the tests. (These 
addresses are placed in the table by the linker.) The VDS uses the table 
when dispatching control to the tests. 



MACRO-32 



$DS_DISPATCH 



BLISS-32 



$DS_DISPATCH; 



NOTES 



In BLISS-32 programs, the .$DS_DISPATCH macro must be placed before 
the $DS_HEADER macro. (Refer to the template m Appendix A.) 



MACRO-32 
EXAMPLE 

$DS DISPATCH 



BLISS-32 
EXAMPLE 

$DS_DISPATCH; 
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$DS_DSDEF 



The $DS_DSDEF macro defines (for MACRO-32 programs) symbolic 
names for status codes returned by system services that begin with the 
prefix DS$_. Status codes beginning with the SS$_ prefix are defined 
by the $SSDEF macro in STARLET. MLB. For BLISS-32 programs, these 
symbols may be referenced without first issuing the $DS_DSDEF macro. 

Symbols defined are: 



DS$_NORMAL 

DS$_SBVERE 

DS$_ILLCHAR 

DS$_NOTDON 

DS$_VASFUL 

DS$~IHWE 

DS$_ILLPAGCNT 

DS$_KRNI,STK 

DS$_CHME 

DS$_ICERR 

DS$_UNEXPINT 

DS$_BADLINK 

DSS_DEVNAME 

DS$_INVCPU 
DSS_NOTALLOWMP 
DSS_INIT_FAIL 
DSS NODE 



DS$_WARNING 

DS$_OVERFLOW 

DS$_PROGERR 

DS$~1WECT 

DS$_1NSFMEM 

DSS~FHWE 

DS$_FRABUF 

DS$_POWER 

DS$_NOTIMP 

DSS_ICBUSY 

DS$_CHMK 

DS$_NEEDUNIT 

DS$~NOPCS 



DSS_ERROR 

DS$_NULLSTR 

DS$_TRUNCATE 

DS$_IVADDR 

DS$~MMOFF 

DS$_LOGIC 

DS$~MCHK 

DS$_TRANSL 

DS$_IPL2HI 

DS$_ARITH 

DS$_BADTYPE 

DS$_ILLUNIT 

DS$ NOSUPPORT 



DS $_MEM_ALLOC_ERR 
DS $_AP_NORMAL_BREAK 
DS$ BIIC 



MACRO-32 



$DS^DSDEF [gbl] 



ARGUMENTS gbl 

Can be LOCAL or GLOBAL 



MACRO-32 
EXAMPLE 

$DS DSDEF GLOBAL 
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$DS_DSSDEF 



The $DS_DSSDEF macro defines (for MACRO-32 programs and BLISS-32 
programs) the symbolic names of entry points for the system services. 

For BLISS-32 programs, the macro must be defined globally in at least 
one source module, as follows: 

GLOBAL $DSSDEF; 

Symbols defined are: 



DS$ABORT 

DS$ASKLGCL 

DS$ATTACH 

DS$ BREAK 

DSSCKLOOP 

DS$CVTREG 

DS$ERRDEV 

DS$ERRSOFT 

DS$FREEDBGSYM 

DS$GPHARD 

DS$INLOOP 

DS$MAPDBGBLOCK 

DS$MOVPHY 

DS$PRINTB 

DS$PRINTSIG 

DS$RELBUF 

DS$SETKAP 

DS$SHOCHAN 

DS$WAITUS 

SYS$ASSIGN 

SYS$CANTIM 

SyS$CONNECT 

SyS$DASSGN 

SYS$GET 

SYS$LKWSET 

SYSSQIO 

SYS$READEF 

SYS$SETIMR 

SYS$SETRWM 

SYS$ULWSET 

SYSSWFLAND 



DS$ASKDATA 

DS9ASKSTR 

DS$BGNSUB 

DS$CANWAIT 

DSSCLRVEC 

DS$ENDPASS 

DS$ERRHARD 

DS$ERRSYS 

DS$GETBUF 

DS$HELP 

DS$LOAD 

DS$MMOFF 

DS$MOWRT 

DS$PRINTF 

DS$PRINTX 

DS$RELMEM 

DS$SETPRIEXV 

DS$SUM(aARY 

SYS $ ALLOC 

SYS$BINTIM 

SYS$CLOSE 

SYS$DISCONNECT 

SYS$FAO 

SyS$GETCHN 

SYSSNUMTIM 

SYS$QIOW 

SYS$SETAST 

SYSSSETPRI 

SYS$SETSWM 

SYS$UNWIND 

SYSSWFLOR 



DS$ASKADR 

DS$ASKVLD 

DS$BRANCH 

DS$CHANNEL 

DS$CNTRLC 

DS$ENDSUB 

DS$ERRPREP 

DS$ESCAPK 

DS$GETMEM 

DS$IMITSCB 

DS$LOADPCS 

DS$MMON 

DS$PARSE 

DS$PRINTS 

DS$PROBE 

DS$SETIPL 

DS$SETVEC 

DS$WAITMS 

SYS$ASCTIM 

SYS$CANCEL 

SYS$CLREF 

SYS$DALLOC 

SYS$FAOL 

SYS$GETTIM 

SYS $ OPEN 

SYS $ READ 

SYS$SETEF 

SYS$SETPRT 

SYS$ULKPAG 

SyS$WAITFR 



MACRO-32 



$DS_DSSDEF [gbl] 



ARGUMENTS gbl 

Can be LOCAL or GLOBAL 



MACRO-32 
EXAMPLE 

$DS DSSDEF GLOBAL 
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$DS.$END 



$DS.$END 



The $DS_$END macro is used to terminate a p-table descriptor. 



MACRO-32 $DS $END 



BLISS-32 



$DS_$END; 



NOTES 



Code generated by macro (shown in Macro-32; Bliss-32 is equivalent): 
.BYTE 0(81 ; End of p-table descriptor 
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$DS^ENDATTACHED— $DS_BGNATTACHED 

In a diagnostic program that tests multiple processors, use the 
$DS_BGNATTACHED and $DS_ENDATTACHED macros to delineate 
code that is to be executed in an attached processor. These macros 
are used whether the code is included in the loadable image of the main 
diagnostic program or it is a separate loadable image. (See Section 4.6.) 

$DS_BGN ATT ACHED indicates the beginning of the code and creates 
a label that can be used with the $DS_STARTATTACHED service. The 
$DS_ENDATTACHED macro generates code that will send the processor 
back to its idle loop. 



MACRO-32 



$DS_BGN ATT ACHED routine_name, mask 



$DS ENDATTACHED 



BLISS-32 



$DS_BGNATTACHED 

(ROUTINE_NAME = routine _name); 



$DS_ENDATTACHED; 



ARGUMENTS routlne_name 

Labels the routine and points to its first instruction. 

mask 

List of register names used in the entry mask. 
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$DS_ENDATTACHED 



NOTES 



1 You can include code that is contained in an attached process in 
any number of separate executable files. The code in each file, 
however, must be position-independent. You can only have one 
attached process, delimited by one set of $DS_BGNATTACHED and 
$DS_END ATTACHED macros, per file. 

2 If you want to place the code in a separate image, request a buffer 
using the $DS_GETBUF service, load the image into the buffer, and 
use the address of the buffer as the "start_addr" argument for the 
$DS_STARTATTACHED macro. 

3 You can enter the code usmg a CALL instruction. 

4 It is recommended that you place data structures for the code in a 
separate psect. If you must include the data structures in the same 
psect as the code, place them (data structures) after the code and end 
the executable section with a $DS_EXrr macro as shown: 

.psect data $DS_BGNATTACHED RTN2 

<data structures> 

<executable code> 

•psect code 

$DS_BGNATTACHED RTNl $DS_EXIT ATTACHED 

<executable code> <data structures> 



$DS ENDATTACHED $DS_ENDATTACHED 
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$DS_ENDCLEAN— $DS_BGNCLEAN 



The $DS_BGNCLEAN and $DS_ENDCLEAN macros are used to delimit 
tile program's clean-up code. These macros create the connections which 
make it possible for the VDS to locate and execute the clean-up code. 



MACRO-32 



$DS_BGNCLEAN [<regmask>], [<psect>] 

(clean-up code) 
$DS_ENDCLEAN 



BLiSS-32 



$DS_BG N C LEAN ; (clean-up code); 
$DS_ENDCLEAN; 



ARGUMENTS 



regmask 

List of general purpose register names to be placed in the entry mask. 

psect 

Any argument string that is valid for a MACRO-32 .PSECT statement. If 
none is specified, the argument string "CLEANUP,LONG" will be used. 



NOTES 



1 In MACRO-32, the $DS_BGNCLEAN macro will generate the following 
code: 



CLEAN UP; 



.SAVE 

. PSECT psect 

.WORD ^M<regmask> 



In MACRO-32, the $DS_ENDCLEAN macro will generate the following 
code: 



CLEAN UP X: 



$DS_BREAK 

RET 

. RESTORE 



2 In BUSS-32, the $DS_BGNCLEAN macro will generate the following 
code: 



%SBTTL 'CLEAN UP' 

PSECT CODE =5 CLEANUP (WRITE); 

GLOBAL ROUTINE CLEAN UP;NOVALUE = 

BEGIN 



In BLISS-32, the $DS_ENDCLEAN macro will generate the following 
code: 



END 
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$DS_ENDCLEAN 



MACRO-32 
EXAMPLE 



$DS_BGNCLEAN <R2, R3,R4, R5>, <CLEANSECT , LONG> 



$DS ENDCLEAN 



BLISS-32 
EXAMPLE 

$DS_BGNCLEAN; 
$DS ENDCLEAN; 
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$DS_ENDDATA 



$DS_ENDDATA— $DS_BGNDATA 



The $DS_BGNDATA and $DS_ENDDATA macros are used to optionally 
provide lists of input arguments to a test. Each time the VDS executes a 
test for which argument lists have been specified, it will execute the code 
within the test once for each argument list. From the user's point of view, 
this repeated execution of the code within a test will appear to be one 
execution of the test. 

The $DS_BGNDATA and $DS_EIMDDATA macros must be located 
immediately before the $DS_BGNTEST macro of the test to which the 
parameter lists belong. 



MACRO-32 



$ DS_BG N DATA [align], argument-list, [argument-list] 



$DS_ENDDATA 



BLISS-32 



This macro is not supported for BLISS-32. 



ARGUMENTS align 



Desired alignment for the psect containing the argument lists. Possible 
values are BYTE, WORD, LONG, QUAD, PAGE, or an integer from to 
9. If an integer is specified, the psect will start at the next address that is a 
mtdtiple of two raised to the power of the integer. 

argument-list 

A list of arguments to be used by the test. Each argument must occupy a 
longword. Each parameter list must be formatted as shown in Figure 5-3. 

$DS_ENDDATA 

The $DS_ENDDATA will provide termination for the set of lists by 
generating a longword of 0. 



NOTES 



The VDS will call the test code with a CALLG instruction. Each time 
the test is called, the address of the next argument list will be used as 
the CALLG instruction's argument list parameter. Thus the arguments 
can be referenced within the test by offsets from the AP. 
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$DS_ENDDATA 



EXAMPLES 

$DS_BGNDATA 

.LONG 4, DATA_1, DATA_2 , DATA_3, DATA_4 

.LONG 4, DATA_5, DATA_6, DATA_7 , DATA~8 

• LONG 4, DATA~1, DATA~3f DATA~7 , DATA~9 

$DS_ENDDATA 
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$DS_ENDINIT 



$DS_ENDINIT— $DS_BGN[NIT 



The $DS_BGNINIT and $DS_ENDINIT macros are used to delimit the 
diagnostic program's initialization code. These macros create the 
connections that make it possible for the VDS to locate and execute 
the initialization code. 



MACRO-32 



$DS_BGNiNIT [<regmask_>], [<psect_>] 

(initialization code) 
$DS_ENDINIT 



BLiSS-32 



$DS_BGNINIT; (initialization code); 
$DS ENDINIT; 



ARGUMENTS 



regmask 

List of general purpose register names to be placed in the entry mask. 

psect 

Any argument string that is valid for a MACRO-32 .PSECT statement. If 
none is specified, the argument string "INITIALIZE,LONG" will be used. 



NOTES 



1 In MACRO-32, the $DS_BGNINIT macro will generate the following 
code: 



INITIALIZE: 



-SAVE 
.PSECT psect 

.WORD '^M<regmask> 



In MACRO-32, the $DS_ENDINIT macro will generate the following 
code: 



INITIALIZE X: 



$DS_BREAK 

RET 

. RESTORE 



2 In BLISS-32, the $DS_BGNINrr macro will generate the following code: 



%SBTTL 'INITIALIZE' 

PSECT CODE = INITIALIZE (WRITE); 

GLOBAL ROUTINE INITIALIZE ! NOVALUE = 

BEGIN 



In BLISS-32, the $DS_ENDINIT macro will generate the following code: 



sds_break; 
end" 
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$DS_ENDINIT 



MACRO-32 
EXAMPLE 

$DS_BGNINIT R2,R3,R4,R5, INITSECT,LONG 



$DS ENDINIT 



BLISS-32 
EXAMPLE 

$DS_BGNINIT; 



$DS_ENDINIT; 
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$DS_ENDMESSAGE 



$DS_ENDMESSAGE— $DS_BGNMESSAGE 



The $DS_BGNMESSAGE and $DS_ENDMESSAGE macros should be used 
to delimit each error reporting routine used in conjunction with the error 
reporting macros ($DS_ERRxxxx). 



MACRO-32 



$DS_BGNMESSAGE [<regmask>] 

(error reporting routine) 
$DS_ENDIVIESSAGE 



BLISS-32 



$DS_BGNMESSAGE 

(ROUTINE_NAME = routine_name); 
(error reporting routine); 
$DS_ENDMESSAGE; 



ARGUMENTS 



NOTES 



regmask 

List of general purpose register names to be placed in the entry mask. 

routine_name 

Symbolic name to be associated with the error reporting routine. 



1 The error reporting routine must use $DS_PRINTB and $DS_PRINTX 
macros to print messages. The most important information should 
be printed first, using $DS_PRINTB macros. The most detailed 
information, such as dumps of device registers, should be printed 
last, using $DS_PRINTX macros. Refer to Section 3.9.1, Error Message 
Formats, for example error messages. 

2 Further details on error reporting routines are listed in the description 
of the error macros ($DS_ERRxxxx). 

3 In MACRO-32, the $DS_BGNMESSAGE macro generates an entry 
mask. The $DS_ENDMESSAGE macro generates a RET instruction. 

4 In BLISS-32, THE $DS_BGNMESSAGE macro generates the following 
code: 

GLOBAL ROUTINE %NAME( routlne_name) (NUM, UNIT, MSGADR, PRLINK, 

PI, P2, P3, P4, P5, P6) ! NOVALUE = 
BEGIN 

The $DS_ENDMESSAGE macro generates the following code: 

RETURN 
END 
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$DS_ENDMESSAGE 



EXAMPLE Refer to the description of the $DS_ERRxxxx macros (later in this chapter) 

for examples of $DS_BGNMESSAGE and $DS_ENDMESSAGE. 
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$DS^ENDMOD— $DS_BGNMOD 

The $DS_BGNMOD and $DS_ENDMOD macros must be included at the 
beginning and end, respectively, of every source module making up the 
diagnostic program. 



IVIACRO-32 



$DS_BGNMOD [env], [tn], [st] 

(source module) 
$DS_ENDMOD 



BLISS-32 



$DS_BGNMOD ([ENV= evn], [TEST= tn]); 

(source module); 
$DS_ENDMOD; 



ARGUMENTS env 

Used to indicate if the program is a level 2 program. If so, this value must 
be 2. Otherwise, the value should be (the default). 

Note: In the past, this parameter was assigned one of four predefined 

values: CEP_FUNCTIONAL, CEP.REPAIR, SEF.FUNCTIONAL, or 
SEP_REPAIR. These symbols are meaningless and should not be used. 
(SEP_FUNCTIONAL) is equivalent to 2. 

tn 

Value representing the number to be assigned to the first test in this 
module, if this module contains tests. Default value is 1. 

St 

Value representing the number to be assigned to the first subtest in this 
module, if this module contains subtests. Default value is 1. 



NOTES 



In BLISS-32, the $DS_BGNMOD and $DS_ENDMOD macros must be 
contained within the bounds of the MODULE and ELUDOM keywords, 
as follows. 



MODULE modnam 
BEGIN 



$DS_BGNMOD ( ) ; 



$DS_ENDMOD; 

END 

ELUDOM 



5-134 



$DS_ENDPASS 



$DS_ENDPASS 



The End-of-Pass system service is used to indicate to the VDS that a 
program pass has been pompleted. This servfce rnqst be included in tiie 
Initialization code of every prograjxi. Refer to Sectidn 3.5, Initiidlizatiori 
Code, fqr an explanation of how the $DS_ENDPASS macro is to be used. 



MACRQ-a2 



$DS_ENDPASS_x; 



BLIS$-32 



$DS_ENDPASS: 



f^ETUBN 
STATUS 



This service does not return a status code. 



MACRO-32 
EXAiyiPLE 



$DS_GPHARD_S - 

LOG_UNIT, PTABI,E_ADDR 
CMPL RO, DS$_ERROR 
BNEQL 10$ 
$DS ENDPASS_S 
10$: 



; Get P-table for next unit. 

; If all units done, 

; then 

; declare end-of-pass 

; else continue. 



BLISS-32 
EXAMPLE 



IF $DS_GPHARD 

(DEviJAM = .LOGUNIT, 
RETADR = PTABLE_ADDR) 
EQL DS$_ERROR THEN $DS_ENDPASS; 



! Get P-table for next unit. 



If all units done, 

declare end-of-pass. 
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$DS_ENDREG-~$DS_BGNREG 



The $DS_BGNREG and $DS_ENDREG macros may be used to delimit a 
storage area in whicli device register contents are placed. 



MACRO-32 



$DS_BG N R EG (register storage area) 
$DS_ENDREG 



BLISS-32 



$DS_BG N R EG ; (register storage area); 
$DS_ENDREG; 



NOTES 



1 In MACRO-32, the $DS_BGNREG macro generates the label 
"DEVREG:." 

In BLISS-32, the $DS_BGNREG macro generates the statement 

OWN DEV_REG : VECTOR [0]; 

2 The $DS_ENDREG does not generate any source code. 
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$DS_ENDSERV— $DS_BGNSERV 



The $DS_BGNSERV and $DS_ENDSERV macros should be used to 
delimit interrupt service routines. 



MACRO-32 



$DS_BGNSERV addr 

(interrupt service routine) 
$DS_ENDSERV 



BLISS-32 



These macros are not supported for BLISS-32. 



ARGUMENTS 



addr 

S5mibolic name to be associated with the interrupt service routine. 



NOTES 



1 The $DS_BGNSERV macro will generate the following code: 

.ALIGN LONG, ; ALIGN ON LONGWORD BOUNDARY 
ADDR: 

PUSHR #'^M<R0,R1> ; SAVE RO AND Rl 

The $DS_ENDSERV macro will generate the following code: 



POPR 

RE I 



#'^M<R0,R1> 



RESTORE RO AND Rl 
RETURN FROM SERVICE 
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$DS^ENDSTAT— $DS_BGNSTAT 



The $DS_BGNSTAT and $DS_ENDSTAT macros should be used to delimit 
the data storage area referenced by the summary routine (see Section 3.7, 
Summary Routines). This data area should contain a set of error counts 
for each unit under test. Thus there must be enough storage space 
allocated to handle the maximum number of device units the diagnostic 
program can test. 



IVIACRO-32 



$DS BGNSTAT (statistics tables) 
$DS_ENDSTAT 



BLISS-32 



$DS_BGNSTAT; (statistics tables); 
$DS ENDSTAT: 



NOTES 



In MACRO-32, the $DS_BGNSTAT macro simply generates the label 
'STATISTIC:'. The $DS_ENDSTAT does not generate any code. 

In BLISS-32, the $DS_BGNSTAT macro generates the following 
statement: 

GLOBAL STATISTIC : VECTOR [0]; 

The $DS_ENDSTAT macro does not generate any code. 
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$DS_ENDSUB— $DS_BGNSUB 



The $DS_BGNSUB and $DS_ENDSUB macros are used to delimit eacli 
subtest existing in any particular test. Refer to Section 3.8, Tests, 
Subtests, and Sections, for a discussion of subtests. 



MACRO-32 



$DS_BGNSUB 
$DS_ENDSUB 



(subtest) 



BLISS-32 



$DS_BGNSUB; 
$DS_ENDSUB; 



(subtest); 



NOTES 



The macro automatically numbers each subtest. Subtests are numbered 
from 1 to N for each test, where N is the total number of subtests 
within the test. 

The $DS_BGNSUB macro generates a call to a VDS routine that will 
record the numbers of the current test and subtest. The $DS_ENDSUB 
macro will generate a call to a VDS routine that will verify that the 
current test and subtest numbers are the same as those stored when 
the $DS_BGNSUB macro was issued. If the numbers do not match, the 
VDS will stop execution of the diagnostic program. 
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$DS_ENDSUMMARY— $DS BGNSUMMARY 



The $DS_BGNSUMIVIARY and $DS_ENDSUMMARY macros are used 
to delimit the summary routine. Summary routines are discussed in 
Section 3.7. 



MACRO-32 



$DS_BGNSUMIVIARY [<regmask>], [<psect>] 

(summary routine) 
$DS_ENDSUMMARY 



BLISS-32 



$DS_BGNSUMMARY; (summary routine): 
$DS_ENDSUMMARY; 



ARGUMENTS 



regmask 

List of general purpose register names to be placed in the entry mask. 

psect 

Any argument string that is valid for a MACRO-32 .PSECT statement. If 
none is specified, the argument string 'SUMMARY, LONG' will be used. 



NOTES 



1 In MACRO-32, the $DS_BGNSUMMARY macro will generate the 
following code: 

.SAVE 
. PSECT psect 
SUMMARY: 

WORD '^M<regmask> ; ENTRY MASK 

In MACRO-32, the $DS_ENDSUMMARY macro will generate the 
following code: 

SUMMARY_X: 

SDS_BREAK 

RET 

. RESTORE 

2 In BLISS-32, the $DS_BGNSUMMARY macro will generate the 
following code: 

PSECT CODE = SUMMARY (WRITE); 
GLOBAL ROUTINE SUMMARY : NOVALUE = 
BEGIN 

In BLISS-32, the $DS_ENDSUMMARY macro will generate the 
following code: 

$DS_BREAK; 
END 
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$DS_ENDTEST— $DS^BGNTEST 



The $DS_BGNTEST and $DS_ENDTEST macros are used to delimit each 
test existing in a diagnostic program. Tests are discussed in Section 3.8, 
Tests, Subtests, and Sections. 



MACRO-32 



$DS_BGNTEST [<section-name,section-name,... >], 

[< regmask >], [align] 

(test code) 
$DS_ENDTEST 



BLISS-32 



$DS_BGNTEST 



$DS_ENDTEST; 



([SECTION = < section-name, 
section-name,... >], 
[TEXT= 'test-name']); 
(test code); 



ARGUMENTS 



section-name 

Name of a program section to which this test belongs. Refer to Section 3.8, 
Tests, Subtests, and Sections. 

regmask 

List of general purpose register names to be placed in the entry mask. 

align 

Desired alignment for the psect containing the argument lists. Possible 
values are BYTE, WORD, LONG, QUAD, PAGE, or an integer from to 
9. If an integer is specified, the psect will start at the next address that is a 
multiple of two raised to the power of the integer. 

text 

Text string identifying the test. This test will be displayed on the user 
terminal each time the test is executed, provided that the user has set the 
VDS control flag TRACE. If the (') character is to be included within the 
text string, it must be specified twice, as in: 

TEXT = 'Fred"s test' 

(In MACRO-32, the identifying message is defined by using the 
$DS_SUBTTL macro.) 
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NOTES 



The $DS_BGNTEST macro will assign a test number to the test. The 
test number is incremented each time the $DS_BGNTEST macro is 
called within a source module. (The test number can be initialized 
when the $DS_BGNMOD macro is called at the beginning of the 
source module.) 

In MACRO-32, the $DS_BGNTEST macro causes the following label to 
be generated: 

TEST_xxx: : .WORD "M< > 

where "xxx" is the current test number. 

In MACRO-32, the $DS_ENDTEST macro generates the following code: 

MOVL #1,R0 ; NORMAL EXIT 
TEST_nnn_X : : 

~$DS_BREAK 
RET~ 

In BLISS-32, the $DS_BGNTEST macro generates the foUowing entry 
point: 

.ENTRY TEST_XXX,^M< > 

where "xxx" is the current test number. 

In BLISS-32, the $DS_ENDTEST macro generates the following code: 

$DS_BREAK; 

ss$~normal 
endT 

$DS_BGNTEST and $DS_ENDTEST are unavailable to attached 
processors in multiprocessing environments. 
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$DS_ERRDEF 



The $DS_ERRDEF macro defines (for MACRO-32 programs) the symbolic 
names of the parameters associated with the $DS_ERRxxxx macros. 
These symbols will most likely be used in error reporting routines. 

For BLISS-32 programs, these symbols are not used in error reporting 
routines because expansion of the $DS_BGNMESSAGE macro produces a 
parameter list for the error reporting routine. 

Refer to descriptions of the $DS_BGNMESSAGE and $DS_ERRxxxx 
macros for examples of referencing $DS_ERRxxxx parameters in error 
reporting routines. 

Symbols defined are: 

ERR$_NUM 

ERR$_UNIT 

ERR$_MSGADR 

ERR$_PRLINK 

ERR$_P1 

ERRS_P2 

ERR$_P3 

ERR$_P4 

ERRS_P5 

ERRS~P6 



MACRO-32 $DS_ERRDEF [gbl] 



ARGUMENTS gbl 

Can be LOCAL or GLOBAL 



NOTES 



These symbols are used as offsets into the argument list, for example, 
ERR$_P3(AP). 



MACRO-32 
EXAMPLE 

$DS ERRDEF GLOBAL 
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$DS^ERRDEV 



There are five error reporting system services used to report to the 
program user any errors encountered by the program that relate to failures 
in the device being tested. 

The $DS_ERRDEV macro is used to report device-fatal errors. It can be 
issued from anywhere in the diagnostic program except the cleanup code. 

The error types are discussed in Section 3.9, Reporting Errors. 

The error reporting system service? will: 

• Display a "header message" consisting of the program title, the pass, 
test, and subtest numbers, and the message specified by the error 
macro's "msgadr" parameter (see below). 

• Cause the message routine specified by the error macro's "priink" 
parameter (see below) to be called. 

• Test the VDS control flags HALT and LOOP. If HALT is set, execution 
of the program will be stopped. If LOOP is set, a program loop will be 
established (see Section 3.10, Looping). 



IVIACRO-32 



$DS_ERRDEV_x [num], [unit], [msgadr], [priink], 

[p1],...[p6] 



BLISS-32 



$DS_ERRDEV ([NUIVI = num], [UNIT= unit], 

[MSGADR = msgadr], 
[PRLINK= priink], 
[P1=p1],...,[P6 = p6]); 



ARGUMENTS 



num 

An identification number assigned to the error macro. If not specified, a 
number is automatically assigned to the error macro at program assembly 
time, according to the following algorithm. 

• The error number is set to 1 at the beginning of each test and each 
subtest. 

• Each time one of the error reporting macros is encountered at assembly 
time, the macro is assigned the current error number and then the error 
nvimber is incremented. 

• If a macro call possesses an argument for the "num" parameter, that 
argument is used and the stored error number is not incremented. 
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Thus, if the default value for "num" is always taken, each error reporting 
macro within a given subtest will have a unique error number assigned to 
it, and for each subtest the error macros will be numbered sequentially 
starting with 1. If the $DS_ERRxxxx_L form of the macro is used, the 
"num" argument must be specified by using the $DS_ERRNUM macro. 

unit 

The logical unit number of the unit currently being tested. 

msgadr 

Address of a counted ASCII string to be included in the error message 
header. Should contain a short description of the error. 

prlink 

Address of an error reporting routine. Routine must be delimited by 
$DS_BGNMESSAGE and $DS_ENDMESSAGE macros and must use 
$DS_PR1NTB and $DS_PRINTX macros for output. 

p1 through p6 

One to six optional parameters that may be used to pass arguments to the 
error reporting routine whose address is contained in "prlink." 



RETURN 
STATUS 



None. 



NOTES 



• Registers R2 through Rll are preserved so that the routine pointed to 
by "prlink" can expect to find them intact. 

• In a multiprocessing environment, $DS_ERRxxxx cannot be called from 
within a block of code delineated by the $DS_BGNATTACHED and 
$DS_ENDATTACHED macros. 

Error Reporting Routines: 

The "prlink" parameter is used to link an error reporting routine to the 
error macro. The error reporting system service first displays the header 
message, including the text pointed to by "msgadr." Then the routine 
pointed to be "prlink" is called. The error reporting routine must have the 
following properties: 

• It is called with a CALLG instruction, so it must have an entry mask. 

• It must be delimited by the $DS_BGNMESSAGE and 
$DS_ENDMESSAGE macros. 

• It must print the second and third levels of the error message 
(see Section 3.9, Reporting Errors) by using the $DS_PRINTB and 
$DS_PRINTX macros, respectively. 

• It can reference arguments passed via the pi through p6 parameters. 
These parameters can be accessed using the symbols defined by the 
$DS_ERRDEF macro. 
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It must contain all of the $DS_PRINTB and $DS_PRINTX macros 
that are used to display the error message. (If $DS_PRINTB and 
$DS_PRINTX macros are used to display an error message, they must 
be contained in an error reporting routine.) 



MACRO-32 
EXAMPLE 



FMT GOODBADi 



FMT_DUMPHDR: 
FMT DUMPBUF: 



Note: 



.ASCIC 



.ASCIC 
.ASCIC 



These examples will produce error messages that adhere to the format 
indicated in Section 6.5.2, Error Message Formats. 

READERRMSG; .ASCIC /READ error while performing block transfer./ 
\!/! /Device base address !_; !_!SL\- 
\!/Address of expected buf f er !_: !_!SL\- 
\!/Address of received buf f er !_: !_tSL\- 
\!/Transfer size (words) !_;!_! SL\- 
\! /Words in error !_: !_!SL\ 

\!/! /ADDRESS: !_EXPECTED: !_RECEIVED: !_XOR; !/!/\ 
\!SL! ISL! !SL! !SL!/\ 



$DS BGNMESSAGE <R2 , R3,R4,R5> 



10$: 



20$: 



30$: 



$DS PRINTS S 



$DS_PRINTX_S 

CLRL 

MOVAL 



FMT_GOODBAD,- 
ERR$_P5 ( AP ) , ERR$ 
ERR$_P3(APf,ERR$. 
FMT DUMPHDR 



MOVAL 

CMPW 
BEQL 



R2 

REC_BUF,R3 

EXP~BUF,R4 



(R3) 
20$ 



.(R4) 



INCL R2 
X0RL3 R3 , R4 , R5 
$DS_PRINTX_S FMT_DUMPBUF,- 

R3,7r4),(R3) ,R5 
CMPL R2,#8 
BEQL 30$ 

CMPL (R3)+,(R4)+ 
CMPL R3,#REC_B0F_SIZE 
BRB 10$ 
$DS ENDMESSAGE 



Print second level of error msg. 
_P2(AP),ERR$_P1(AP), - 
-P4(AP) 

Print header for buffer dump 

Clear error count 

Get addr. of received buffer 

Get addr. of expected buffer 

REPEAT 

See if this word is good. 
IF word is bad 
; THEN 

; Count the error. 
; XOR good and bad data 
; Print a line of 3rd msg, level 

; IF eight bad words displayed, 
; THEN stop. 

; Increment buffef pointers. 
; See if top of bufJEer reached. 
! UNTIL entire buffer done. 



$DS BGNTEST 



$DS_ERRHARD_S UNIT=LOG_UNIT, MSGADR=READERRMSG , 
PRLINK=BUFDUMP, - 

P1=REC_BUF, P2=EXP_BUF, - 
P3=#REC_BUF_SIZE, P4=ERR~C0UNT, - 
P5=DEV BASE 



$DS_ENDTEST 
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BLISS-32 
EXAMPLE 



LITERAL 
BIND 



REC_BUF_SIZE = 256; 

READERRMSG = 

UPLIT (%ASCIC 'READ error performing block transfer.'); 



OWN 



REC_BUF ; VECTOR [REC_BUF_SIZE,WORD] , 
EXP_BUF : VECTOR [REC_BUF_SIZE,WORD] , 
LOG_UNIT , ERR_COaNT , DEV_BASE ; 



$DS_BGNMESSAGE ( ROUTINE_NAME=BUFDUMP) 
LOCAL 



BIND 



ERRORS, 
XOR_VALUE; 



FMT_G00DBAD1= 

UPLIT (%ASCIC '!/!/Device base address 1_: !_! SL' ) , 
FMT_G00DBAD2= 

UPLIT (%ASCIC '!/Address of expected buffer !_:!_! SL' ) , 
FMT_GaODBAD3= 

UPLIT (%ASCIC '!/Address of received buffer !_:!_! SL' ) , 
FMT_G00DBAD4= 

UPLIT (%ASCIC '!/Transfer size (words) !_: !_!SL' ) , 
FMT_G00DBAD5= 

UPLIT (%ASCIC ''/Words in error !_:!_! SL' ) , 
FMT_DUMPHDR= 

UPLIT (%ASCIC ' •/!/ADDRESS:!_EXPECTED! !_RECEIVED: !_XOR: !/!/') , 
FMT_DUMPBUF= 

UPLIT (%ASCIC • !SL!_!SL!_!SL!_!SL!/' ); 



! Display the second level of the error message. 

$DS_PRINTB (FMT_GOODBAD1,P5) 

$DS_PRINTB ( FMT_GO0DBAD2 , P2 ) 

$DS~PRINTB ( FMT~GO0DBAD3 , P 1 ) 

$DS_PRINTB ( FMT_GO0DBAD4 , P3 ) 

$DS_PRINTB ( FMT_GO0DBAD5 , P4 ) 

! Display the third level of the error message. 

! First print the header and clear the error count. 

$DS_PRINTX (FMT_DUHPHDR) ; ! Print header for buffer dump. 
ERRORS =0; ! Clear error count 
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! Now compare the expected buffer with the received buffer. Display all 
! mismatches. If more than eight errors are found, we can stop. 

INCR INDEX FROM TO REC_BUF_SIZE DO 
BEGIN 

IF .REC_BUF [.INDEX] NEQ .EXP_BUF [.INDEX] 
THEN 

BEGIN 

ERRORS = .ERRORS + 1; 

XOR_VALUE = 

.REC_BUF [.INDEX] XOR . EXP_BUF [.INDEX]; 
SDS_PRINTX (FMT_DUMPBUF, 

REC_BUF [ .INDEX], 
.EXP_BUF [.INDEX], 
. REC_BUF [ . INDEX ] , 
.XOR__VALUE); 
END; 
IF .ERRORS EQL 8 THEN EXITLOOP; 
END; 

$DS_ENDMESSAGE; 



$DS_BGNTEST (TEXT='Read tests'); 



SDS_ERRHARD (UNIT=.LOG_UNIT, MSGADR=READERRMSG, 

PRLINK=BUFDOMP, P1=REC_BUF, 

P2=EXP_BUF, P3=REC_BUF_SIZE, 

P4=.ERR_C0UNT, P5=. DEV_BASE) ; 



$DS_ENDTEST; 
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$DS_ERRHARD 



There are five error reporting system services used to report to the 
program user any errors encountered by the program that relate to failures 
in the device being tested. 

The $DS_ERRHARD macro is used to report hard errors. It can be issued 
only from within tests (see Section 3.8.1). 

The error types are discussed in Section 3.9, Reporting Errors. 

The error reporting system services will: 

• Display a "header message" consisting of the program title, the pass, 
test, and subtest numbers, and the message specified by the error 
macro's "msgadr" parameter (see below). 

• Cause the message routine specified by the error macro's "priink" 
parameter (see below) to be called. 

• Test the VDS control flags HALT and LOOP. If HALT Is set, execution 
of the program will be stopped. If LOOP is set, a program loop will be 
established (see Section 3.10, Looping). 



MACRO-32 



$DS_ERRHARD_x [num], [unit], [msgadr], [priink], 

[p1h-[p6] 



BLrSS-32 



$DS_ERRHARD ([NUM = num], [UNIT= unit], 

[MSGADR = msgadr], 
[PRLINK= priink], 
[P1=p1],...,[P6 = p6]); 



ARGUMENTS 



num 

An identification number assigned to the error macro. If not specified, a 
number is automatically assigned to the error macro at program assembly 
time, according to the following algorithm. 

• The error number is set to 1 at the beginning of each test and each 
subtest. 

• Each time one of the error reporting macros is encountered at assembly 
time, the macro is assigned the current error number and then the error 
number is incremented. 

• If a macro call possesses an argument for the "num" parameter, that 
argument is used and the stored error number is not incremented. 
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Thus, if the default value for "num" is always taken, each error reporting 
macro within a given subtest will have a unique error number assigned to 
it, and foF each subtest the error macros will be numbered sequentially 
starting with 1. If the $DS_ERRxxxx_L form of the macro is used, the 
"num" argument must be specified by using the $DS_ERRNU]VI macro. 

unit 

The logical unit number of the unit currently being tested. 

msgadr 

Address of a counted ASCII string to be included in the error message 
header. Should contain a short description of the error. 

priink 

Address of an error reporting routine. Routine must be delimited by 
$DS_BGNMESSAGE and $DS_ENDMESSAGE macros and must use 
$DS_PRINTB and $DS_PRINTX macros for output. 

pi through p6 

One to six optional parameters that may be used to pass arguments to the 
error reporting routine whose address is contained in "priink." 



RETURN 
STATUS 



None. 



NOTES 



• Registers R2 through Rll are preserved so that the routine pointed to 
by "priink" can expect to find them intact. 

• In a multiprocessing environment, $DS_ERRxxxx cannot be called from 
within a block of code delineated by the $DS_BGNATTACHED and 
$DS_END ATTACHED macros. 

Error Reporting Routines: 

The "priink" parameter is used to link an error reporting routine to the 
error macro. The error reporting system service first displays the header 
message, including the text pointed to by "msgadr." Then the routine 
pointed to be "priink" is called. The error reporting routine must have the 
following properties: 

• It is called with a CALLG instruction, so it must have an entry mask. 

• It must be delimited by the $DS_BGNMESSAGE and 
$DS_ENDMESSAGE macros. 

• It must print the second and third levels of the error message 
(see Section 3.9, Reporting Errors) by using the $DS_PRINTB and 
$DS_PRINTX macros, respectively. 

• It can reference arguments passed via the pi through p6 parameters. 
These parameters can be accessed using the symbols defined by the 
$DS_ERRDEF macro. 



5-150 



$DS_ERRHARD 



It must contain all of the $DS_PRINTB and $DS_PRINTX macros 
that are used to display the error message. (If $DS_PRINTB and 
$DS_PRINTX macros are used to display an error message, they must 
be contained in an error reporting routine.) 



MACRO-32 
EXAMPLE 



Note: These examples will produce error messages that adhere to the format 
indicated in Section 6.5.2, Error Message Formats. 



FMT GOODBAD; 



FMT_DUMPHDR: 
FMT~DUMPBUF! 



.ASCIC 



.ASCIC 
.ASCIC 



E?EADERRMSG; .ASCIC /READ error while performing block transfer./ 
\!/!/Device base address!_; !_!SL\- 
\! /Address of expected buf fer !_:!_! SL\- 
\! /Address of received buf fer !_;!_! SL\- 
\! /Transfer size (words) !_:!_! SL\- 
\! /Words in error !_: !_!SL\ 

\!/!/ADDRESS: !_EXPECTED: !_RECEIVED! !_XOR! !/!/\ 
\!SL! !SL! ! SlT !SL!/\ 



BUFDUMP ! 



$DS BGNMESSAGE <R2 , R3 , R4 , R5> 



$DS PRINTS S 



$DS_PRINTX_S 
CLRL 



FMT_GOODBAD,- ; Print second level of error msg. 
ERR$_P5 ( AP ) , ERR$_P2 ( AP ) , ERR$_P 1 ( AP ) , - 
ERR$_P3(AP) ,ERR$_P4(AP) 



FMT DUMPHDR 



10$: 



MOVAL 
MOVAL 

CMPW 
BEQL 

INCL 
X0RL3 



R2 

REC_BUF,R3 

EXP_BUF,R4 

(R3),(R4) 
20$ 

R2 

R3 , R4 , R5 



$DS PRINTX_S 



CMPL 
BEQL 



R2,#8 
30$ 



FMT_DUMPBUF,- 
R3, (R4) , (R3),R5 



20$! 



30$: 



CMPL ( R3 ) + , ( R4 ) + 
CMPL R3,#REC_BUF_SIZE 
BRB 10$ 
$DS ENDMESSAGE 



Print header for buffer dump 

Clear error count 

Get addr. of received buffer 

Get addr. of expected buffer 

REPEAT 

See if this word is good. 

IF word is bad 

THEN 

Count the error. 

XOR good and bad data 

Print a line of 3rd msg. level 

IF eight bad words displayed, 
THEN stop. 

Increment buffer pointers. 
See if top of buffer reached. 
UNTIL entire buffer done. 



$DS_BGNTEST 



$DS_ERRHARD_S UNIT=LOG_UNIT, MSGADR=READERRMSG , 
PRLINK=BIJFDUMP, - 

P1=REC_BUF, P2=EXP_BUF, - 

P3=#REC_BUF_SIZE, P4=ERR_C0UNT, - 
P5=DEV BASE 



$DS ENDTEST 
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BLISS-32 
EXAMPLE 



LITERAL 

REC_BUF_SIZE = 256; 



BIND 



OWN 



READERRMSG = 

UPLIT (%ASCIC 'READ error performing block transfer. 

REC_BUF : VECTOR [REC_BUF_SIZE,WORD] , 
EXP_BUF : VECTOR [ REC_BUF_ SIZE, WORD] , 
L0G_UN1T,ERR_C0UNT,DEV BASE; 



$DS_BGNMESSAGE ( ROUTINE_NAME=BUFDUMP) 

LOCAL 

ERRORS, 
XOR_VALUE; 

BIND 

FMT_G00DBAD1= 

UPLIT (%ASCIC ''/"/Device base address!_; !_!SL' ) , 
FMT_GOODBAD2= 

UPLIT (%ASCIC '!/Address of expected buf f er !_; !_1SL' ) , 
FMT_G0ODBAD3= 

UPLIT (%ASCIC '! /Address of received buf f er !_! !_!SL' ) , 
FMT_G0ODBAD4= ~ 

UPLIT (%ASCIC '! /Transfer size (words) !_:!_! SL' ) , 
FMT_G00DBAD5= 

UPLIT (%ASCIC '!/Words in error !_! !_!SL' ) , 
FMT_DUMPHDR= 

UPLIT (%ASCIC ' !/!/ADDRESS:!_EXPECTED: !_RECEIVED;!_XOR! !/!/' ), 
FMT_DUMPBUF= 

UPLIT (%ASCIC ' !SL!_!SL!_!SL!_!SL!/' ); 

! Display the second level of the error message. 

$DS_PRINTB ( FMT_G0ODBAD 1 , P5 ) ; 

$DS~PRI NTS ( FMT_G00DBAD2 , P2 ) ; 

$DS_PRINTB (FMT_G00DBAD3,P1) ; 

$DS_PRINTB ( FMT_G00DBAD4 , P3 ) ; 

$DS_PRINTB ( FMT_G00DBftD5 , P4 ) ; 

! Display the third level of the error message. 

1 First print the header and clear the error count. 

SDS_PRINTX (FMT_DUMPHDR); ! Print header for buffer dump. 
ERRORS =0; ! Clear error count 
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! Now compare the expected buffer with the received buffer. Display all 
I mismatches. If more than eight errors are found, we can stop. 

INCR INDEX FROM TO REC_BUF_SIZE DO 
BEGIN 

IF .REC_BUF [.INDEX] NEQ .EXP_BUF [.INDEX] 
THEN 

BEGIN 

ERRORS = .ERRORS + 1; 

XOR_VALUE = 

..REC_BUF [.INDEX] XOR .EXP_BUF [.INDEX]; 
$ DS_PRINTX ( FMT_DUMPBUF , 

REC_BUF [.INDEX], 
. EXP_BUF [ . INDEX ] , 
. REC_BUF [ . INDEX ] , 
. XOR_VALUE ) ; 
END; 
IF .ERRORS EQL 8 THEN EXITLOOP; 
END; 

$DS_ENDMESSAGE; 



$DS_BGNTEST (TEXT='Read tests'); 



$DS_ERRHARD (UNIT=.LOG_UNIT, MSGADR=READERRMSG , 

PRLINK=BUFDUMP, P1=REC_BUF, 

P2=EXP_BUF, P3=REC_BUF_SIZE, 

P4= . ERR_COUNT , P5= . DEV_BASE ) ; 



$DS ENDTEST; 
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$DS_ERRNUM 



The $DS_ERRNUM macro is used in conjunction with the $DS_ERRxxxx_L 
macros, it generates executabie code that will dynamically load the 
"num" argument of the argument list created by the $DS_ERRxxxx_L 
macro. 



MACRO-32 $DS_ERRNUM label, [num] 



BLISS-32 



Not supported for BLISS-32. 



ARGUMENTS 



label 

Address of the argument list generated by the $DS_ERRxxxx_L macro. 

num 

Error number. If a value is specified, the value will be used as the "num" 
parameter in the argument list. If a value is not specified, the current 
assembly-time error number is used. Refer to the description of the 
$DS_ERRxxxx system services for an explanation of the assignment of error 
numbers at assembly time. 



NOTES 



Using the $DS_ERRxxxx_L macro to create an argument list, dynamically 
altering the error number with the $DS_ERRNUM macro, then calling the 
error service with a $DS_ERRxxxx_G call has a disadvantage. It is difficult 
to relate a specific error message, displayed at run-time, to a specific point 
in the program listing because the error number is not explicitly specified 
as a macro argument. This may or may not be a problem, depending on 
the program's use and users. 



EXAMPLE 



ARG_LISTs 

$DS_ERRHARD_L - 

UNIT = LOG_UNIT, - 
MSGADR = HARD_MSG1, 
PRLINK = HARD_RTN1, 
PI - CSR REG 



; Declare hard error arg. list 



$DS ERRNUM ARG LIST 



;Put error number in arg. list 
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$DS_ERRPREP 



There are five error reporting system services used to report to the 
program user any errors encountered by the program that relate to failures 
in the device being tested. 

The $DS_ERRPREP macro is used to report device preparation errors. 
It can be issued from anywhere in the diagnostic program except the 
cleanup code. 

The error types are discussed in Section 3.9, Reporting Errors. 

The error reporting system services will: 

• Display a "header message" consisting of the program title, the pass, 
test, and subtest numbers, and the message specified by the error 
macro's "msgadr" parameter (see beiow). 

• Cause the message routine specified by the error macro's "prlinl<" 
parameter (see below) to be called. 

• Test the VDS control flags HALT and LOOP. If HALT is set, execution 
of the program will be stopped, if LOOP is set, a program loop will be 
established (see Section 3.10, Looping). 



MACRO-32 



$DS_ERRPREP_x 



[num], [unit], [msgadr], [priink], 
[p1L-[p6] 



BLISS-32 



$DS_ERRPREP 



([NUM = num], [UNIT= unit], 
[MSGADR = msgadr], 
[PRLlNK=prlink], 
[P1=p1],...,[P6 = p6]); 



ARGUMENTS 



num 

An identification number assigned to the error macro. If not specified, a 
number is automatically assigned to the error macro at program assembly 
time, according to the following algorithm. 

• The error number is set to 1 at the beginning of each test and each 
subtest. 

• Each time one of the error reporting macros is encountered at assembly 
time, the macro is assigned the current error number and then the error 
number is incremented. 

• If a macro call possesses an argument for the "num" parameter, that 
argument is used and the stored error number is not incremented. 
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Thus, if the default value for "num" is always taken, each error reporting 
macro within a given subtest will have a unique error number assigned to 
it, and for each subtest the error macros will be numbered sequentially 
starting with 1. If the $DS_ERRxxxx_L form of the macro is used, the 
"num" argument must be specified by using the $DS_ERRNUM macro. 

unit 

The logical unit number of the unit currently being tested. 

msgadr 

Address of a counted ASCII string to be included in the error message 
header. Should contain a short description of the error. 

priink 

Address of an error reporting routine. Routine must be delimited by 
$DS_BGNMESSAGE and $DS_ENDMESSAGE macros and must use 
$DS_PRINTB and $DS_PRINTX macros for output. 

pi through p6 

One to six optional parameters that may be used to pass arguments to the 
error reporting routine whose address is contained in "priink." 



RETURN 
STATUS 



None. 



NOTES 



• Registers R2 through Rll are preserved so that the routine pointed to 
by "priink" can expect to find them intact. 

• In a multiprocessing environment, $DS_ERRxxxx cannot be called from 
within a block of code delineated by the $DS_BGNATTACHED and 
$DS_ENDATTACHED macros. 

Error Reporting Routines: 

The "priink" parameter is used to link an error reporting routine to the 
error macro. The error reportmg system service first displays the header 
message, including the text pointed to by "msgadr." Then the routine 
pointed to be "prlirJ<" is called. The error reporting routine must have the 
following properties: 

• It is called with a CALLG instruction, so it must have an entry mask. 

• It must be delimited by the $DS_BGNMESSAGE and 
$DS_ENDMESSAGE macros. 

• It must print the second and third levels of the error message 
(see Section 3.9, Reporting Errors) by using the $DS_PRINTB and 
$DS_PRINTX macros, respectively. 

• It can reference arguments passed via the pi through p6 parameters. 
These parameters can be accessed using the symbols defined by the 
$DS_ERRDEF macro. 



5-156 



$DS_ERRPREP 



It must contain all of the $DS_PRINTB and $DS_PRINTX macros 
that are used to display the error message. (If $DS_PRINTB and 
$DS_PRINTX macros are used to display an error message, they must 
be contained in an error reporting routine.) 



MACRO-32 
EXAMPLE 



Note: These examples will produce error messages that adhere to the format 
indicated in Section 6.5.2, Error Message Formats. 



FMT GOODBAD: 



FMT_DUMPHDR! 
FMT~DUMPBUF: 



.ASCIC 



.ASCIC 
.ASCIC 



READERRMSG: .ASCIC /READ error while performing block transfer./ 
\!/! /Device base address !_: !_!SL\- 
\!/Address of expected buf f er !_! !_!SL\- 
\! /Address of received buf f er !_; l_!SL\- 
\!/Transfer size (words) !_! !_!SL\- 
\! /Words in error !_! !_!SL\ 

\ !/! /ADDRESS ! !_EXPECTiD: !_RECEIVED: !_XOR: !/!/\ 
\!SL! !SL! ! SlT !SL!/\ 



BUFDUMP: 



$DS_BGNMESSAGE <R2 , R3 , R4 , R5> 



$DS_PR1HTB_S 



$DS_PRINTX_S 

CLRL 

MOVAL 

MOVAL 



FMT_GOODBAD,- ; Print second level of error msg. 
ERR$_P5(AP) ,ERR$_P2(AP) ,ERR$_P1(AP) , - 
ERR$_P3 ( AP ) , ERR$_P4 ( AP ) 
FMT DUMPHDR 



10$: 



CMPW 
BEQL 

INCL 
XORL3 



R2 

REC_BUF,R3 

EXP~BUF,R4 

(R3),(R4) 

20$ 

R2 

R3 , R4 , R5 



$DS_PRINTX_S 



CMPL 
BEQL 



R2,*8 
30$ 



FMT_DUMPBUF,- 
R3 , ( R4 ) , ( R3 ) , R5 



Print header for buffer dump 

Clear error count 

Get addr. of received buffer 

Get addr. of expected buffer 

REPEAT 

See if this word is good. 

IF word is bad 

THEN 

Count the error . 

XOR good and bad data 

Print a line of 3rd msg. 



level 



20$! 



30$: 



CMPL (R3)+,(R4)+ 
CMPL R3,#REC_BUF_SIZE 
BRB 10$ 

$DS ENDMESSAGE 



IF eight bad words displayed, 
THEN stop. 

Increment buffer pointers. 
See if top of buffer reached. 
UNTIL entire buffer done. 



$DS BGNTEST 



$DS_ERRHARD S UNIT=LOG_UNIT, MSGADR=READERRMSG , 
PRLINK=BUFDUMP, - 
P1=REC_BUF, P2=EXP_BUF, - 
P3=#REC_B0F_SIZE, P4=ERR~C0UNT, - 
P5=DEV BASE 



$DS_ENDTEST 
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BLISS-32 
EXAMPLE 



LITERAL 



BIND 



OWN 



REC BUF SIZE 



256; 



READERRMSG = 

UPLIT (%ASCIC 'READ error performing block transfer.')) 

REC_BUF : VECTOR [ REC_BUF_SIZE,WORD] , 
EXP_BUF ! VECTOR [ REC_BUF~SIZE,WORD] , 
LOG_UNIT , ERR_COUNT , DEV_BASE ; 



$DS_BGNMESSAGE ( ROUTINE_NAME=BUFDUMP ) 

LOCAL 

ERRORS, 
XOR_ VALUE; 

BIND 



FMT_G00DBAD1= 

UPLIT (%ASCIC '!/!/Device base addresB!_: !_!SL' ) , 
FMT_G00DBAD2= 

UPLIT (%ASCIC '!/Address of expected buffer!_:! !SL'), 
FMT_G0ODBAD3= 

UPLIT (%ASCIC '!/Address of received buffer! :! !SL'), 
FMT_G00DBAD4= 

UPLIT (%ASCIC '! /Transfer size (words)!_;l !SL'), 
FMT_G00DBAD5= 

UPLIT (%ASCIC '! /Words in error !_:! !SL'), 
FMT_DUMPHDR= 

UPLIT (%ASCIC '!/: /ADDRESS; !_EXPECTED: ! RECEIVED:! XOR:!/!/'), 
FMT_DUMPBUF= 

UPLIT (%ASCIC ' !SL!_!SL!_!SL!_!SL!/' ); 

1 Display the second level of the error message. 

$DS_PRINTB (FMT_G00DBAD1,P5) 

$DS_PRINTB ( FMT_G00DBAD2 , P2 ) 

$DS_PRINTB (FMT_G00DBAD3,P1) 

$DS_PRINTB ( FMT~G00DBAD4 , P3 ) 

$DS_PRINTB ( FMtIgOODBADB , P4 ) 

! Display the third level of the error message. 

1 First print the header and clear the error count. 

$DS_PRINTX (FMT_DUMPHDR); ! Print header for buffer dump. 
ERRORS =0; i Clear error count 
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1 Now compare the expected buffer with the received buffer. Display all 
I mismatches. If more than eight errors are found, we can stop. 

I NCR INDEX FROM TO REC_BUF_SIZE DO 
BEGIN 

IF .REC_BUF [.INDEX] NEQ . EXP_BUF [.INDEX] 
THEN 

BEGIN 

ERRORS = .ERRORS + 1; 

XOR_VALtrE = 

.REC_BUF [.INDEX] XOR . EXP_BUF [.INDEX]; 
$DS_PRINTX ( FMT_DUMPBUF , 

REC_BUF [.INDEX], 
.EXP_BUF [ .INDEX], 
.REC_BUF [ .INDEX], 
. XOR~VALUE ) ; 
END; 
IF .ERRORS EQL 8 THEN EXITLOOP; 
END; 

$DS_ENDMES5AGE; 



$DS_BGNTEST (TEXT=' Read tests ') ; 



$DS_ERRHARD (UNIT=. LOG_UNIT, MSGADR=READERRMSG , 

PRLINK=BUFDOMP, P1=REC_BUF, 

P2=EXP_BUF, P3=REC_BUF_SIZE, 

P4= . ERR_COUNT , P5= . DEV_BASE ) ; 



$DS ENDTEST; 
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$DS_ERRSOFT 



There are five error reporting system services used to report to the 
program user any errors encountered by the program that relate to failures 
in the device being tested. 

The $DS_Ei=»RSOFT macro is used to report soft errors. It can be issued 
only from within tests (see Section 3.8.1). 

The $DS_ERRSYS macro is used to report system-fatal errors. It can be 
issued from anywhere in the diagnostic program except the cleanup code. 

The error types are discussed in Section 3.9, Reporting Errors. 

The error reporting system services will: 

• Display a "header message" consisting of the program title, the pass, 
test, and subtest numbers, and the message specified by the error 
macro's "msgadr" parameter (see below). 

• Cause the message routine specified by the error macro's "priink" 
parameter (see below) to be called. 

• Test the VDS control flags HALT and LOOP. If HALT is set, execution 
of the program will be stopped. If LOOP is set, a program loop will be 
established (see Section 3.10, Looping). 



MACRO-32 



$DS_ERRSOFT_x [num], [unit], [msgadr], [priink], 

[p1],...[p6] 



BLfSS-32 



$DS_ERRSOFT ([NUM = num], [UNIT = unit], 

[MSGADR = msgadr], 
[PRLINK= priink], 
[P1=p1],....[P6 = p6]); 



ARGUMENTS "*"" 



An identification number assigned to the error macro. If not specified, a 
number is automatically assigned to the error macro at program assembly 
time, according to the following algorithm. 

• The error number is set to 1 at the beginning of each test and each 
subtest. 

• Each time one of the error reporting macros is encountered at assembly 
time, the macro is assigned the current error number and then the error 
number is incremented. 

• If a macro call possesses an argument for the "num" parameter, that 
argument is used and the stored error number is not incremented. 
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Thus, if the default value for "num" is always taken, each error reporting 
macro within a given subtest will have a unique error number assigned to 
it, and for each subtest the error macros will be numbered sequentially 
starting with 1. If the $DS_ERRxxxx_L form of the macro is used, the 
"num" argument must be specified by using the $DS_ERRNUM macro. 

unit 

The logical unit number of the unit currently being tested. 

msgadr 

Address of a counted ASCII string to be included in the error message 
header. Should contain a short description of the error. 

priink 

Address of an error reporting routine. Routine must be delimited by 
$DS_BGNMESSAGE and $DS_ENDMESSAGE macros and must use 
$DS_PRINTB and $DS_PRINTX macros for output. 

pi through p6 

One to six optional parameters that may be used to pass arguments to the 
error reporting routine whose address is contained in "priink." 



RETURN 
STATUS 



None. 



NOTES 



• Registers R2 through Rll are preserved so that the routine pointed to 
by "priink" can expect to find them intact. 

• In a multiprocessing environment, $DS_ERRxxxx cannot be called from 
within a block of code delineated by the $DS_BGN ATTACHED and 
$DS_ENDATTACHED macros. 

Error Reporting Routines: 

The "priink" parameter is used to link an error reporting routine to the 
error macro. The error reporting system service first displays the header 
message, including the text pointed to by "msgadr." Then the routine 
pointed to be "priink" is called. The error reporting routine must have the 
following properties: 

• It is called with a CALLG instruction, so it must have an entry mask. 

• It must be delimited by the $DS_BGNMESSAGE and 
$DS_ENDMESSAGE macros. 

• It must print the second and third levels of the error message 
(see Section 3.9, Reporting Errors) by using the $DS_PRINTB and 
$DS_PRINTX macros, respectively. 

• It can reference arguments passed via the pi through p6 parameters. 
These parameters can be accessed using the S3niibols defined by the 
$DS_ERRDEF macro. 
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It must contain aU of the $DS_PRINTB and $DS_PRINTX macros 
that are used to display the error message. (If $DS_PRINTB and 
$DS_PRINTX macros are used to display an error message, they must 
be contained in an error reporting routine.) 



MACRO-32 
EXAMPLE 



FMT GOODBAD: 



FMT_DUMPHDRl 
FMT DUMPBUFi 



Note: These examples will produce error messages that adhere to the format 
indicated in Section 6.5.2, Error Message Formats. 

READERRMSG: .ASCIC /READ error while performing block transfer./ 

.ASCIC \!/I/Device base address!_: !_!SL\- 
\t/Address of expected buf fer !_: !_!SL\- 
\l/Address of received buffer!_: l_!SL\- 
\I/Transfer size (words) 1_: !_!SL\- 
\! /Words in error !_ i !_!SL\ 

.ASCIC \!/! /ADDRESS: •_EXpicTED:l_RECEIVED: ! XOR:I/!/\ 

.ASCIC \!SL!_!5L! ! SlT !SLI/\ 



BUFDUMP: 



$DS_BGNMESSAGE <R2 , R3 , R4 , R5> 

$DS_PRINTB_S FMT_GOODBAD,- ; Print second level of 

ERRS_P5(AP),ERR$_P2(AP),ERR$_P1(AP), - 

ERR$_P3 ( AP ) , ERR$_P4 ( AP ) 



error msg. 



$DS_PRINTX_S 

CLRL 

MOVAL 



PMT DUMPHDR 



10$: 



MOVAL 

CMPW 
BEQL 



R2 

REC_BUF,R3 

EXP_BUF,R4 



(R3),(R4) 
20$ 



INCL R2 
X0RL3 R3,R4,R5 
$DS_PRINTX_S FMr_DUMPBUF,- 

R3,7r4),(R3),R5 
CMPL R2,#8 
BEQL 30$ 

20$: CMPL (R3)+,(R4)+ 

CMPL R3,#REC_BUF_SIZE 
BRB 10$ 

30$: $DS ENDMESSAGE 



Print header for buffer dump 

Clear error count 

Get addr. of received buffer 

Get addr. of expected buffer 

REPEAT 

See if this word is good. 

IF word is bad 

THEN 

Count the error. 

XOR good and bad data 

Print a line of 3rd msg. level 

IF eight bad words displayed, 
THEN Stop. 

Increment buffer pointers. 
See if top of buffer reached. 
UNTIL entire buffer done. 



$DS BGNTEST 



$DS_ERRHARD_S UNIT=LOG_UNIT, MSGADR=READERRMSG , 
PRLINK-BUFDUMP, - 
P1=REC_BUF, P2=EXP_BUF, - 
P3=#REC_BUF_SIZE, P4-ERR_C00NT, - 
P5=DEV IaSE 



$DS ENDTEST 
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BLISS-32 
EXAMPLE 



OWN 



LITERAL 

REC_BUF_SIZE = 256; 
BIND 

READEREOTSG = 

UPLIT (%ASCIC 'READ error performing block transfer.'); 

REC_BUF : VECTOR [REC_BUF_SIZE,WORD] , 
EXP_BUF ! VECTOR [ REC_BUF_SIZE, WORD] , 
LOG_UNIT , ERR_COUNT , DEV_BASE ; 



$DS_BGNMESSAGE ( ROUTINE_NAME=BUFDUMP ) 

LOCAL 

ERRORS , 
XOR_VALUE; 

BIND 

FMT_G00DBAD1= 

UPLIT (%ASCIC '!/!/Device base address!_: !_!SL' ) , 
FMT_G00DBAD2= 

UPLIT (%ASCIC '!/Address of expected buffer !_:!_! SL' ) , 
FMT_G00DBAD3= 

UPLIT (%ASCIC ''/Address of received buffer !_:!_! SL' ) , 
FMT_GOODBAD4 = 

UPLIT (%ASCIC '! /Transfer size (words )!_: !_!SL' ) , 
FMT_G00DBAD5= 

UPLIT (%ASCIC '!/Words in error !_:!_! SL' ) , 
FMT_DUMPHDR= 

UPLIT (%ASCIC ' !/!/ADDRESS! !_EXPECTED: !_RECEIVED: !_X0R: !/!/' ), 
FMT_DUMPBUF= 

UPLIT (%ASCIC ' !SL!_!SL!_!SL!_!SL!/' ) ; 

! Display the second level of the error message. 

$DS_PRINTB ( FMT_GOODBADl , P5 ) ; 
$D5_PRINTB ( FMT_G00DBAD2 , P2 ) ; 
$DS_PRINTB ( FMT_G00DBAD3 , PI ) ; 
$DS_PRINTB ( FMT~G00DBAD4 , P3 ) ; 
$DS_PRINTB ( FMT_G00DBAD5 , P4 ) ; 

! Display the third level of the error message. 

! First print the header and clear the error count. 

$DS_PRINTX {FMT_DUMPHDR) ; ! Print header for buffer dump. 
ERRORS =0; ! Clear error count 
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! Now compare the expected buffer with the received buffer. Display all 
! mismatches. If more than eight errors are found, we can stop. 

INCR INDEX FROM TO REC_BUF_SIZE DO 
BEGIN 

IF .REC_BUF [.INDEX] NEQ .EXP_BUF [.INDEX] 
THEN 

BEGIN 

ERRORS = .ERRORS + 1; 

XOR_VALUE = 

.REC_BUF [.INDEX] XOR . EXP_BUP [.INDEX]; 
$DS_PRINTX (FMT_DUMPBUF, 

REC_BUF [ .INDEX], 
.EXP_BUF [.INDEX], 
.REC~BUF [.INDEX], 
.XOR_VALUE) ; 
END; 
IF .ERRORS EQL 8 THEN EXITLOOP; 
END; 

$DS_ENDMESSAGE ; 



$DS_BGNTEST (TEXT='Read tests' 



$DS_ERRHARD (UNIT=.LOG_UNIT, MSGADR=READERRMSG, 

PRLINK=BUFDUMP, P1-REC_BUF, 

P2=EXP_BUF, P3=REC~BUF_SIZE, 

P4= . ERR_COUNT , P5= . DEV_BASE ) ; 



$DS_ENDTEST; 
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$DS_ERRSYS 



There are five error reporting system services used to report to tiie 
program user any errors encountered by tiie program tliat relate to failures 
in the device being tested. 

The $DS_ERRSYS macro is used to report system-fatal errors. It can be 
issued from anywhere in the diagnostic program except the cleanup code. 

The error types are discussed in Section 3.9, Reporting Errors. 

The error reporting system services will: 

• Display a "header message" consisting of the program title, the pass, 
test, and subtest numbers, and the message specified by the error 
macro's "msgadr" parameter (see below). 

• Cause the message routine specified by the error macro's "priink" 
parameter (see below) to be called. 

• Test the VDS control flags HALT and LOOP. If HALT is set, execution 
of the program will be stopped. If LOOP is set, a program loop will be 
established (see Section 3.10, Looping). 



MACRO-32 



$DS ERRSYS_x [numj, [unit], [msgadr], [priink], 

[p1L-[p6] 



BLISS-32 



$DS_ERRSYS ([NUM = nam], [UNIT = unit], 
[MSGADR = msgadr], 
[PRUNK = priink], 
[P1=p1],...,[P6 = p6]); 



ARGUMENTS num 



An identification number assigned to the error macro. If not specified, a 
number is automatically assigned to the error macro at program assembly 
time, according to the following algorithm. 

• The error number is set to 1 at the beginning of each test and each 
subtest. 

• Each time one of the error reporting macros is encountered at assembly 
time, the macro is assigned the current error number and then the error 
number is incremented. 

• If a macro call possesses an argument for the "num" parameter, that 
argument is used and the stored error number is not incremented. 
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Thus, if the default value for "num" is always taken, each error reporting 
macro within a given subtest will have a unique error number assigned to 
it, and for each subtest the error macros will be numbered sequentially 
starting with 1. If the $DS_ERRxxxx_L form of the macro is used, the 
"num" argument must be specified by using the $DS_ERRNUM macro. 

unit 

The logical unit number of the unit currently being tested. 

msgadr 

Address of a counted ASCII shring to be included in the error message 
header. Should contain a short description of the error. 

priink 

Address of an error reporting routine. Routine must be delimited by 
$DS_BGNMESSAGE and $DS_ENDMESSAGE macros and must use 
$DS_PRINTB and $DS_PRINTX macros for output. 

pi through p6 

One to six optional parameters that may be used to pass arguments to the 
error reporting routine whose address is contained in "priink." 



RETURN 
STATUS 



None. 



NOTES 



• Registers R2 through Rll are preserved so that the routine pointed to 
by "priink" can expect to find them intact. 

• In a multiprocessing environment, $DS_ERRxxxx cannot be called from 
within a block of code delineated by the $DS BGNATTACHED and 
$DS_ENDATTACHED macros. 

Error Reporting Routines: 

The "priink" parameter is used to link an error reporting routine to the 
error macro. The error reporting system service first displays the header 
message, including the text pointed to by "msgadr." Then the routine 
pointed to be "priink" is called. The error reporting routine must have the 
following properties: 

• It is called with a CALLG instruction, so it must have an entry mask. 

• It must be delimited by the $DS_BGNMESSAGE and 
$DS_ENDMESSAGE macros. 

• It must print the second and third levels of the error message 
(see Section 3.9, Reporting Errors) by using the $DS_PRINTB and 
$DS_PRINTX macros, respectively. 

• It can reference arguments passed via the pi through p6 parameters. 
These parameters can be accessed using the symbols defined by the 
$DS_ERRDEF macro. 
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It must contain all of the $DS_PRINTB and $DS_PRINTX macros 
that are used to display the error message. (If $DS_PRINTB and 
$DS_PRINTX macros are used to display an error message, they must 
be contained in an error reporting routine.) 



MACRO-32 
EXAMPLE 



Note: These examples will produce error messages that adhere to the format 
indicated in Section 6.5.2, Error Message Formats. 



FMT GOODBAD! 



FMT_DUMPHDR: 
FMT~DUMPBUF! 



.ASCIC 



.ASCIC 
•ASCIC 



READERRMSG! .ASCIC /READ error while performing block transfer./ 
\!/!/Device base address !_; !_1SL\- 
\1/Address of expected buf f erl_! !_1SL\- 
\!/Address of received buf fer !_;!_! SL\- 
\! /Transfer size (words) !_: !_!SL\- 
\t/Words in error!_: !_!SL\ 

\ •/! /ADDRESS I •_EXpicTiD: !_RECKIVED: !_XOR: !/I/\ 
\!SL! !SL! !SlT !SL1/\ 



BUFDUMPI 



$DS BGNMESSAGE <R2 , R3 , R4 , R5> 



$DS PRINTB S 



$DS_PRINrX_S 
CLRL 



10$! 



20$: 



30$: 



FMT_GOODBAD,- ; Print second level of error msg. 
ERRS_P5 ( AP ) , ERR$_P2 (AP) , ERR$_P1 ( AP > , - 
ERR$_P3 ( AP ) , ERR$_P4 ( AP ) 



FMT DUMPHDR 



MOVAL 
MOVAL 

CMPW 
BEQL 

INCL 
X0RL3 



R2 

REC_BUF,R3 

EXP_BUF,R4 

(R3),(R4) 
20$ 

R2 

R3 , R4 , R5 



$DS PRINTX S 



CMPL 
BEQL 



R2,#8 
30$ 



FMT_DUMPBUF,- 
R3,7r4), (R3),R5 



Print header for buffer dump 

Clear error count 

Get addr. of received buffer 

Get addr. of expected buffer 

REPEAT 

See if this word is good. 

IF word is bad 

THEN 

Count the error. 

XOR good and bad data 

Print a line of 3rd msg. 



level 



CMPL (R3)+,(R4)+ 
CMPL R3,#REC_BUF_SIZE 
BRB 10$ 
$DS ENDMESSAGE 



IF eight bad words displayed, 
THEN stop. 

Increment buffer pointers. 
See if top of buffer reached. 
UNTIL entire buffer done. 



$DS_BGNTBST 



$DS_ERRHARD_S UNIT=LOG_UNIT, MSGADR=READERRMSG , 
PRLINK=BUFDUMP, - 

P1=REC_BUF, P2=EXP_BUF, - 
P3=#REC_BUF_SIZE, P4=ERR_C0UNT, - 
P5=DEV iASE~ 



$DS ENDTEST 
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BLISS-32 
EXAMPLE 



LITERAL 
BIND 



OWN 



REC_BUF_SIZE = 256; 

READERRMSG = 

UPLIT (%ASCIC 'READ error performing block transfer.'); 

REC_BUF : VECTOR [ REC_BUF_SIZE, WORD] , 
EXP_BUF : VECTOR [REC_BUF_SIZE,WORD] , 
LOG_UN I T , ERR_COUNT , DEV_BASE ; 



$DS_BGNMESSAGE ( ROUTINE_NAME=BUFDUMP ) 

LOCAL 

ERRORS , 
XOR_VALUE ; 

BIND 



FMT_G00DBAD1= 

UPLIT (%ASCIC '!/! /Device base address! !!_!SL'), 
FMT_GOODBAD2= 

UPLIT (%ASCIC '[/Address of expected buf fer !_: l_!SL' ) , 
FMT_G00DBAD3= 

UPLIT (%ASCIC '[/Address of received buffer!_;! !SL'), 
FMT_G00DBAD4= 

UPLIT (%flSCIC ''/Transfer size (words)! :1 !SL'), 
FMT_G00DBAD5= 

UPLIT (%ASCIC '! /Words in error !_;! !SL'), 
FMT_DUMPHDR= 

UPLIT (%ASCIC ' i/l/ADDRESS: !_EXPECTED: !_RECEIVED; !_X0R! !/!/' ), 
FMT_DUMPBUF= 

UPLIT (%ASCIC ' !SL!_!SL!_!SL!_!SL!/' ); 

! Display the second level of the error message. 

$DS_PRINTB (FMT_G00DBAD1,P5) 

$DS_PRINTB ( FMT_G00DBAD2 , P2 ) 

SDS_PRINTB ( FMT_G00DBAD3 , PI ) 

$DS_PRINTB ( FMT_G00DBAD4 , P3 ) 

$DS_PRINTB ( FMT~G00DBAD5 , P4 ) 

! Display the third level of the error message. 

! First print the header and clear the error count. 

$DS_PRINTX (FMT_DUMPHDR); ! Print header for buffer dump. 
ERRORS =0; ! Clear error count 
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! Now compare the expected buffer with the received buffer. Display all 
I mismatches. If more than eight errors are found, we can stop. 

INCR INDEX FROM -TO REC_BUF_SIZE DO 
BEGIN 

IF .REC_BUF [.INDEX] NEQ .EXP_BUF [.INDEX] 
THEN 

BEGIN 

ERRORS = .ERRORS + 1; 

XOR_VALUE = 

.REC_BUF [.INDEX] XOR . EXP_BUF [.INDEX]; 
$DS_PRINTX (FMT_DUMPBUF, 

REC_BUF [.INDEX], 
.EXP_BUF [ .INDEX], 
.REC_BUF [.INDEX], 
. XOR~VALUE ) ; 
END; 
IF .ERRORS EQL 8 THEN EXITLOOP; 
END; 

$DS ENDMESSAGE; 



$DS_BGNTEST (TEXT='Read tests'); 



$DS_ERRHARD (UNIT=.LOG_UNIT, MSGADR=READERRMSG , 

PRLINK=BUFDOMP, Pl=REC_BUF, 

P2=EXP_BUF, P3=REC_BUF_SIZE, 

P4= . ERR_COUNT , P5= . DEV_BASE ) ; 



$DS_ENDTEST; 
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$DS_ESCAPE 



The $DS_ESCAPE program control macro can be used to exit from a 
test or subtest if a hardware failure has been detected from within the 
test or subtest. If the failure is reported using one of the error reporting 
macros ($DS_ERRxxxx), and if $DS_ESCAPE is executed before the next 
$DS_ENDSUB or $DS_ENDTEST macro is encountered, program control 
will branch to the next $DS_ENDSUB or $DS_ENDTEST (whichever is 
specified). 



MACRO-32 



$DS_ESCAPE arg 



BLISS-32 



Not supported for BLISS-32. See Note 1. 



ARGUMENTS arg 



Indicates whether program control should branch to nearest $DS_ENDSUB 
or nearest $DS_ENDTEST. The argument may be either SUB or TEST. 



NOTES 



1 For programs written in BLISS-32, similar hmctionality can be obtained 
by following the $DS_ERRxxxx macro with a LEAVE statement, as 
shown in the example below. 



MACRO-32 
EXAMPLE 

$DS_BGNSUB 



$DS_ERRHARD UNIT=LOG_UNIT, MSGADR=HRDMSG3 , PRLINK=HRDRTN3 
$DS ESCAPE SUB 



$DS ENDSUB 



5-170 



$DS_ESCAPE 



BLISS-32 
EXAMPLE 

$DS_BGNSUB; 
SUB3! BEGIN 



$DS_ERRHARD_S (UNIT=.LOG_UNIT, MSGADR=HRDMSG3 , PRLINK=HRDRTN3 ) ] 
LEAVE SUB3;~ 



END; 

$DS ENDSUB; 
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$DS_EXIT 



The $DS_EXIT program control macro is used to unconditionally branch to 
the end of the currently executing program segment. Exits can be made 
from any of the following: 

• A test 

• A subtest 

• An interrupt service routine 

• The summary routine 

• Code that is executing in an attached processor (See Section 4.6, VDS 
in a Multiprocessing Environment). 



MACRO-32 $DS_EXIT arg 



BLISS-32 



Not supported for BLISS-32. See Note 1. 



ARGUMENTS arg 



Indicates program segmeiit type. Valid arguments are TEST, SUB, SERV, 
SUMMARY, and ATTACHED. 



NOTES 



1 For programs written in BLISS-32, similar functionality can be obtained 
by using the LEAVE statement, as shown in the example below. 



MACRO-32 
EXAMPLE 

$DS BGNSERV SERV RTN 



SDS EXIT SERV 



$DS ENDSERV 
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BLISS-32 
EXAMPLE 



$DS_BGNTEST; 
T2_BLK1 I 

BEGIN 



LEAVE T2 BLKl; 



END; 
$DS_ENDTEST; 
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$FAB 



The $FAB macro is used to allocate an RMS file access block (FAB) at 
program compilation time and, optionally, to load values into the various 
fields within the FAB. An FAB is a data structure that is required for 
performing file management operations using RMS. Refer to Section 4.5, 
File Management. 

This description only discusses FAB fields supported by VDS RMS. For 
a discussion of VMS RMS-supported fields, refer to the VAX/VMS RMS 
Reference Manual. 

Besides allocating the FAB, the $FAB macro also defines symbols for each 
FAB field. Symbols are of the form "FAB$datatype_fleldname," where 
"datatype" is a data type specifier listed in Section 4.5.4. 



MACRO-32 



$FAB DNA = default-name-addressr 

DNM = <defau^t-name-fHespec>,- 
DNS = default-string-size,- 
FAC = fac-param,- 
FNA = filename-address,- 
FNM = < filename-filespeo,- 
FNS = filename-string-size,- 
FOP = RWOr 
FSZ = header-size, - 
XAB = xab-addr 



BLISS-32 



$ F A B DNA = default-name-address, 
DNM= 'default-name-filespec', 
DNS = default-string-size, 
FAC = fac-param, 
FN A = filename-address, 
FNM= 'filename-filespec', 
FNS = filename-string-size, 
FOP = RWO, 
FSZ = header-size, 
XAB=xab-addr; 
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ARGUMENTS ^^^ parameters are optional. Refer to descriptions of the RMS run-time 

services to determine which fields are required for which services. Fields 
may be loaded at run-time with the $FAB_STORE macro, or by directly 
referencing FAB fields, as described in Section 4.5.4. 

DNA = default-name-address 

Address of a character string representing defaults to be used for the 
filename, if the actual filename specification is incomplete. The default 
string may contain all or some of the following fields: 

• Node 

• Device 

• Device directory 

• Filename 

• Filename extension 

• File version number 

An example default string is 

DEF_STRING: .ASCII /.DAT/ 

The DNS field must be used in conjunction with the DNA field. 

DNM = default-name-filespec 

A character string representing defaults to be used for the filename, if the 
actual filename specification is incomplete. Using the DNM parameter is 
an alternative to using the DNA and DNS parameters. 

A MACRO-32 example of this parameter is DNM= <.EXE;0>. A BLISS-32 
example is DNM = '.EXE;0'. 

DNS = default-string-size 

Size of the string pointed to by "default-name-address." Used only if the 
DNA parameter is also used. 

FAC = fac-param 

File access parameters. If the program is to perform $GET or $READ 
operations, the FAC field must be set up before the $OPEN operation is 
performed. Following are valid file access parameters: 

• BIO — Block I/O operations ($READ) will be performed. 

• BRO - Both Block I/O ($READ) and Record I/O ($GET) operations will 
be performed. 

• GET - Record I/O operations ($GET) will be performed. This is the 
default. 
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FNA = filename-address 

Address of character string representing the name of the file on which 
operations are to be performed. If any filename components are missing 
from the string, those components will be extracted from the default string 
specified by either the DNA or the DNM parameter. If components are 
still missing, they will be defaulted to the fields that would be exhibited if 
a SHOW LOAD user command were issued. 

The FNS parameter must be used in conjunction with the FNA parameter. 

FNM = filename-filespec 

Character string representing the name of the file on which operations are 
to be performed. This parameter is an alternative to the FNA and FNS 
parameters, and would most likely be used in programs that always open 
the same file. An example in BLISS-32 would be FNM = EVABC.DAT. 

FNS = filename-strlng'Slze 

Size of character string pointed to by "filename-address." The FNS 
parameter is used only if the FNA parameter is also used. 

FOP = RWO 

Rewind on open. Indicates that a magnetic tape should be rewound before 
a file on the tape is opened. 

FSZ = header-size 

Size of file's fixed control area. Used only for files containing fixed-length 
control records. Refer to the VAXn'MS RMS Reference Manual for details. It 
is unlikely that a diagnostic program will make use of this field. 



XAB = xab-addr 

Address of the FHC XAB, 
$XABFHC macro.) 



if used. (The FHC XAB is declared with the 



NOTES 



Read-Only FAB Fields 

The following FAB fields are not loaded by the programmer under VDS 
RMS. They are filled in by RMS services, and may be read after the service 
has completed. (Some of these fields are read/write in VMS RMS.) 

• BID — Block identifier field. Indicates to RMS that a block is an FAB. 

• BLN — Block length field. Defines the length of the FAB. 

• DEV — Device characteristics field. A bitmap indicating various 
characteristics of the device on which the file being referenced resides. 
Following is a list of bits supported by VDS RMS: 

— DIR — Directory-structured device. 

— FOD — File-oriented device (disk and magnetic tape). 

— RND — Random access device. 

— SDI — Single directory device (master file directory only). 

— SQD — Sequential block-oriented dcAdce (magnetic tape). 
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• IFI — Internal fUe identifier field. Used to associate the FAB with an 
internal access block. 

• MRS — Maximum record size. 

• ORG — File organization. Valid values for this field are: 

— REL — Relative file organization. 

— IDX — Indexed file organization. 

— SEQ — Sequential file organization. 

Note: VDS RMS only supports operations on files having sequential 
organization. 

• RAT — Record attributes. Indicates that special control information 
has been attached to the records of a file. Refer to the VAX/VMS RMS 
Reference Manual for a discussion of record attributes. It is unlikely that 
a diagnostic program will make use of this field. 

• RFM — Record format. Indicates the format of the records in the file. 
Possible values for this field are: 

— FIX - (FAB$C_FIX) Fixed length record format. 

— VFC - (FAB$C_VFC) Variable length with fixed length control 
record format. 

— VAR — (FAB$C_VAR) Variable length record format. 

— UDF - (FAB$C_UDF) Undefined record format. 

— If the file is on the console medium (RT-11 format), the RFM code 
returned by the $OFEN service will be 4. There is no symbolic 
repesentation for this value. 

• STS — Completion status code field. RMS services load this field with 
a success or failure completion status before returning to the caller of 
the service. The completion status code is also passed to the caller in 
RO. 

• STV — Status value field. Sometimes used to pass additional status 
information from a service to the caller. 
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Table 5-4 lists all of the FAB fields. 



Table 5-4 FAB Fields 



Field and 

Keyword 

Name 


Field Size 


Description 


Offset 


ALQ 


Longword 


Allocation quantity 


FAB$L_ALQ 


BID 


Byte 


Block identifier 


FAB$B_BID 


BKS 


Byte 


Bucl<et size 


FAB$B_BKS 


BLN 


Byte 


Block length 


FAB$B_BLN 


BLS 


Word 


Block size 


FAB$W_BLS 


CTX 


Longword 


Context 


FAB$L_CTX 


DEQ 


Word 


Default file extension 
quantity 


FAB$W_DEQ 


DEV 


Longword 


Device characteristics 


FAB$L_DEV 


DNA 


Longword 


Default file specification 
string address 


FAB$L_DNA 


DNS 


Byte 


Defaulf file specification 
strinng size 


FAB$B_DNS 


FAC 


Byte 


File access 


FAB$B_FAC 


FNA 


Longword 


File specification string 
addr. 


FAB$L_FNA 


FNS 


Byte 


File specification string size 


FAB$B_FNS 


FOP 


Longword 


File-processing options 


FAB$L_FOP 


FSZ 


Byte 


Fixed control area size 


FAB$B_FSZ 


IF! 


Word 


Internal file identifier 


FAB$W_IFI 


MRN 


Longword 


Name block address 


FAB$L_MRN 


MRS 


Word 


Maximum record size 


FAB$W_MRS 


NAM 


Longword 


Name block address 


FAB$L_NAM 


ORG 


Byte 


File organization 


FAB$B_ORG 


RAT 


Byte 


Record attributes 


FAB$B_RAT 


RFM 


Byte 


Record format 


FAB$B_RFM 


RTV 


Byte 


Retrieval window size 


FAB$B_RTV 


SDC 


Longword 


Spooling device 
characteristics 


FAB$L_SDC 


SHR 


Byte 


File sharing 


FAB$B_SHR 


STS 


Longword 


Completion status code 


FAB$L_STS 


STV 


Longword 


Status values 


FAB$L_STV 


XAB 


Longword 


Extend attribute block 
address 


FAB$L_XAB 
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MACRO-32 
EXAMPLE 



FAB_BLOCK: $FAB DNM=<.EXE>, - 
FAC=BIO, - 
FNA=FILE_NAME, - 
FNS=FILE~NAME SIZE 



BLISS-32 
EXAMPLE 



OWN 

FAB_BLOCK : $FAB (FAC=GET, - 

FNH= ' EVXYZ . DAT ' ) ; 
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$FABJNIT— $FAB_STORE 



The $FAB_STORE and $FABJNIT macros can be used to load FAB 
fields at run time. The $FAB_STORE macro is used for MACRO-32 
programs. The $FAB_INiT macro is used in BLISS-32 programs. Refer to 
the discussion of the $FAB macro for a description of FAB fields. 



BLISS-32 



SFABJNIT 



FAB = fab = address, 

DNA = default-name-address, 

DNM = 'default-name-filespec', 

DNS = default-string-size, 
FAC = fac-param, 
FN A = filename-address, 
FNM= 'filename-filespec', 
FNS = filename-string-size, 
FOP = RWO, 
FSZ = header-size, 
XAB=xab-addr; 



NOTES 



Refer to the discussion of the $FAB macro for descriptioiis of input 
parameters. With the exception of FAB_address, all parameters are 
optional. 



BLISS-32 
EXAMPLE 

OWN IN_FAB: $FAB (FAC=GET) 



$FAB INIT 



(FAB=IN_FAB, 
FNM=' FILE1.DAT' 
FOP=RWO); 
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$FAB_STORE— $FABJNIT 



The $FAB_STORE and $FAB_INIT macros can be used to load FAB 
fields at run time. The $FAB_STORE macro is used for MACRO-32 
programs. The $FAB_INIT macro is used in BLISS-32 programs. Refer to 
the discussion of the $FAB macro for a description of FAB fields. 



MACRO-32 



$FAB_STORE FAB = fab-address,- 

DNA = default-name-address,- 
DNM= <default-name-filespec>,- 
DNS = default'Strihg-sizer 
FAC-fac-param,- 
FNA = filename-addressr 
FNM = < filename-filespeor 
FNS = filename-string-size,- 
FOP = RWOr 
FSZ = header-size,- 
XAB = xab-addr 



NOTES 



Refer to the discussion of the $FAB macro for descriptions of input 
parameters. With the exception of FAB_address, all parameters are 
optional. 



MACRO-32 
EXAMPLE 



IN FAB: 



$FAB 



$FAB STORE 



FAB=IN_FAB,- 
FNM=<FILE1.DAT>, 
XAB=XABFHC ADDR 
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$FAO-~$FAOL 



The Formatted ASCII Output ($FAO) system service provides a means by 
which complex messages can be formatted into ASCII character strings. 
This macro can be used to: 

• Insert variable character string data into an output string. 

• Convert binary values into the ASCII representations of their decimal, 
hexadecimal, or octal equivalents and substitute the results into an 
output string 

The system service constructs an output string by referring to formatted 
ASCII output (FAG) directives contained in a "control string" and using 
those directives to operate on the contents of value parameters. 

The $FAOL macro performs the exact same function as the $FAO macro, 
but allows the specification of an address of a parameter list instead of 
requiring each parameter to be listed explicitly In the macro call. 



MACRO-32 



$FAO_x ctrstr [outlen], outbuf, [p 1], [p2], . . .[pnj 
$FAOL_x ctrstr [outlen], outbuf, prmlst 



BLISS-32 



$FAO (ctrstr, [outlen], outbuf, [pi], [p2], ...[pn]);) 
$FAOL (CTRSTR = ctrstr, [OUTLEN = outlen], 
OUTBUF = outbuf, PRMLST = prmlst);) 



ARGUMENTS 



ctrstr 

Address of a character string descriptor (see Section 5.3) pointing to the 
"control string." The control string contains a set of Formatted ASCII 
Output (FAQ) directives. These directives are described in the notes of the 
$DS_PRINTx macros. 

outlen 

Address of a word to receive length of output string constructed by the 
service routine. 

outbuf 

Address of a character string descriptor (see Section 5.3) pointing to the 
output buffer. The fully formatted output string is placed in this buffer. 

pi through pn ($FAO only) 

to 20 directive parameters, contained in longwords. Depending on the 
corresponding FAO directive, a parameter may be a value that is to be 
converted, the address of a string that is to be inserted, a length, or an 
argument count. Parameters are listed in the order they are referenced by 
the control string. If more than 20 parameters must be specified, use the 
$FAOL macro. 
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prmlst ($FAOL only) 

Address of a list of longwords containing the directive parameters. The 
list may be of any length. It may be an already existing data structure from 
which certciin values are to be extracted. 



RETURN 
STATUS 



SS$_NORMAL 
SS$_BUFFEROVF 

SS$_BADPARAM 



Service successfully completed. 

Service successfully completed, but the size of the 
output string was greater than the maximum allowed 
and was truncated (see notes) . 

An invalid FAO directive was specified in the control 
string. 



NOTES 



If the formatted output string is to be displayed on the user's terminal, it is 
important to select the proper $DS_PRINTx macro to cause the message to 
be displayed. Refer to the description of the $DS_PRINTx macros. 



MACRO-32 
EXAMPLE 



This example will create the following string: 



VALUES 200 (DEC) O0OO012C (HEX) -400 (SIGNED) 



FAODESC : 

.LONG 80 
.LONG FAOBUF 

FAOBOF: . BLKB 80 

FAOLEN: .BLKW 1 



; Descriptor for output buffer 

; Output buffer length 

;Address of buffer 

; 80-character buffer 

;Word to receive length of output 



CNTRL_STRING! 

.ASCID /VALUES !UL (DEC) 
VALl: .LONG 20O 
VAL2! .LONG 300 
VAL3: .LONG -400 



$FAO_S CTRSTR=CNTRL_STRING, - 
0UTBUF=FA0DESC, - 
0UTLEN=FA0LEN, - 
P1=VAL1, P2=VAL2, P3=VAL3 



!XL (HEX) !SL (SIGNED)/ 
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BLISS-32 
EXAMPLE 



OWN 



FAOBUF 
FAODESC 


: VECTOR [80, BYTE], 
: VECTOR [2] 




INITIAL (80, FAOBUF), 


FAOLEN 
VALl 


: VECTOR [1, WORD], 
: VECTOR 


VAL2 


INITIAL (200) , 
: VECTOR 




INITIAL (300), 


VAL3 


: VECTOR 




INITIAL (-400); 



BIND 



UPLIT = (%ASCID 'VALUES !UL (DEC) ! XL (HEX) !SL (SIGNED)'); 

$FAO (CNTRL_STRING, 
FAODESC , 
FAOLEN, 
VALl, VAL2, VAL3); 
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$FAOL— $FAO 



The Formatted ASCII Output ($FAO) system service provides a means by 
which complex messages can be formatted into ASCII character strings. 
This macro can be used to: 

• Insert variable character string data into an output string. 

• Convert binary values into the ASCII representations of their decimal, 
hexadecimal, or octal equivalents and substitute the results into an 
output string 

The system service constructs an output string by referring to formatted 
ASCII output (FAG) directives contained in a "control string" and using 
those directives to operate on the contents of value parameters. 

The $FAOL macro performs the exact same function as the $FAO macro, 
but allows the specification of an address of a parameter list instead of 
requiring each parameter to be listed explicitly in the macro call. 



MACRO-32 



$FAO_x ctrstr [outlen], outbuf, [p1], [p2], ...[pn] 
$FAOL_x ctrstr [outlen], outbuf, prmlst 



BLISS-32 



$FAO (ctrstr, [outlenj, outbuf, [p1], [p2], ...[pr)]};) 
$FAOL (CTRSTR = ctrstr, [OUTLEN = outleri], 
OUTBUF = outbuf, PRMLST = prmlst);) 



ARGUMENTS 



ctrstr 

Address of a character string descriptor (see Section 5.3) pointing to the 
"control string." The control string contains a set of Formatted ASCII 
Output (FAO) directives. These directives are described in the notes of the 
$DS_PRINTx macros. 

outlen 

Address of a word to receive length of output string constructed by the 
service routine. 

outbuf 

Address of a character string descriptor (see Section 5.3) pointing to the 
output buffer. The fully formatted output string is placed in this buffer. 

p1 through pn ($FAO only) 

to 20 directive parameters, contained in longwords. Depending on the 
corresponding FAO directive, a parameter may be a value that is to be 
converted, the address of a string that is to be inserted, a length, or an 
argument count. Parameters are listed in the order they are referenced by 
the control string. If more than 20 parameters must be specified, use the 
$FAOL macro. 
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prmlst ($FAOL only) 

Address of a list of longwords containing the directive parameters. The 
list may be of any length. It may be an already existing data structure from 
which certain values are to be extracted. 



RETURN 
STATUS 



SS$_NORMAL 
SS$_BUFFEROVF 

SS$_BADPARAM 



Service successfully completed. 

Service successfully completed, but tfie size of the 
output string was greater than the maximum allowed 
and was truncated (see notes). 

An invalid FAO directive was specified in the control 
string. 



NOTES 



If the formatted output string is to be displayed on the user's terminal, it is 
important to select the proper $DS_PRINTx macro to cause the message to 
be displayed. Refer to the description of the $DS_PRINTx macros. 



MACRO-32 
EXAMPLE 



This example will create the following string: 



VALUES 200 (DEC) 0000012C (HEX) -400 (SIGNED) 



FAODESC ! 

.LONG 80 
.LONG FAOBUF 

FAOBUF: .BLKB 80 

FAOLEN! .BLKW 1 



; Descriptor for output buffer 

; Output buffer length 

;Address of buffer 

;80-character buffer 

;Word to receive length of output 



CNTRL_STRING; 

.ASCID 
VALl: .LONG 200 
VAL2i .LONG 300 
VAL3: .LONG -400 



/VALUES !0L (DEC) !XL (HEX) ! SL (SIGNED)/ 



$FAO_S CTRSTR=CNTRL_ STRING, - 
0UTBUF=FA0DESC, - 
0UTLEN=FA0LEN, - 
P1=VAL1, P2=VAL2, P3=VAL3 
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EXAMPLE 



$FAOL 



OWN 



FAOBUF ! VECTOR [80, BYTE], 
FAODESC : VECTOR [2] 

INITIAL (80, FAOBUF), 
FAOLEN : VECTOR [1, WORD], 
VAIil ; VECTOR 

INITIAL (2O0), 
VAL2 ; VECTOR 

INITIAL (3O0), 
VAL3 : VECTOR 

INITIAL (-400); 



BIND 



UPLIT = (%ASCID 'VALUES !UL (DEC) ! XL (HEX) ! SL (SIGNED)'); 

$FAO (CNTRL_STRING, 
FAODESC, 
FAOLEN, 
VALl, VAL2, VAL3); 



5-187 



$DS_$FETCH 



$DS_$FETCH 



The $DS_$FETCH macro is used in p-table descriptors. It will extract the 
contents of a field within the p-table, and store the contents, right-justified, 
in the "value register" (see Section 3.2.3.3). It is possible to reference a 
device-dependent field that was filled with a previous $DS_$STORE macro, 
or device-independent field that was filled by the VDS. The macro can also 
be used to facilitate temporary storage, by storing a value in the p-table 
while the value register is needed for something else, then restoring the 
old value. 



MACRO-32 $DS_$FETCH offset, pos, size 



BLISS-32 



$DS_$FETCH (OFFSET = offset, POS = pos, 
SIZE = size); 



ARGUMENTS offset 



The byte offset into the p-table of the field from which the contents are to 
be fetched. 

pos 

Bit position of the field, relative to the beginning of the byte specified by 
"offset." If the field starts on a byte boundary, this value will be 0. 

size 

Number of bits making up the field. The size cannot be larger than 32. 



NOTES 



1 Code generated by macro (shown in Macro-32; Bliss-32 is equivalent): 



.BYTE '^X87 

.WORD offset 

. BYTE pos 

.BYTE size 



; Beginning of FETCH directive 

; Word data structure offset 

; Bit position in word 

; Bit field size 
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MACRO-32 
EXAMPLE 



$DS_$FETCH OFFSET=HP$A_DVA, POS=0, SIZK=32 
$DS_$FETCH <^x40>, 0, 32 



BLiSS-32 
EXAMPLE 

$DS_$FETCH ( OFFSET=%FIELDEXPAND( HP$A_DVA, ) , 
POS=%FIELDEXPAND(HP$A_DVA, 1 ) , 
SIZE=%FIELDEXPAND( HP$A_DVA, 2 ) ) ; 

$DS_$FETCH (OFFSET=%X'40' , POS=0, SIZ=32); 
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$GET 



The Get a Record service of RMS is used to read a record from a fiie. The 
fiie must have been previously opened and connected with the $OPEN 
and $CONNECT services, respectiveiy. Records may be read from the file 
sequentially or by the random-by-RFA method. These access methods are 
discussed in Section 4.5, File iVIanagement. 



MACRO-32 



$GET rab, [err], [sue] 



BLISS-32 



$G ET (RAB = rab, [ERR = err], [SUC = sue]); 



ARGUMENTS rab 



RETURN 
STATUS 



Address of the RAB to be associated with the FAB describing the file to 
which connection is to be made. (The address of the FAB is in the RAB.) 

err (user mode only) 

Address of a routine to be executed on error return from the service. 

SUC (user mode only) 

Address of a routine to be executed on successful return from the service. 



RMS$_NORMAL 

RMS$_EOF 

RMS$_FAB 

RMSSJFI 

RMS$JSI 

RMS$_RAB 

RMS$_RER 

RMS$_RFA 
RMS$_RTB 



Service successfully completed. 

Attempt was made to read beyond end of file. 

The FAB block Is invalid. 

The FAB's IFI field is invalid. 

The FiAB's ISI field is invalid. 

The RAB block is invalid. 

Read error. (Ttie device driver's return status will be 
in the STV field of the RAB.) 

Invalid RFA was specified in random-by-RFA mode. 

Record retrieved was too big for the buffer provided, 
and was truncated. 



Note: For further details on return status values, refer to the VAX-11 RMS 
Reference Manual. 
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NOTES 



1 Table 5-5 lists the RAB fields used by the $GET service IN 

STANDALONE MODE. For user mode, refer to the VAX-11 RMS 
Reference Manual. 

Table 5-5 RAB Fields Used by $GET (Standalone Mode) 



Field Mnemonic 



Field Name 



input: 

ISI 

RAC 

RFA 

ROP 

UBF 

USZ 

Output: 

RBF 

RFA 

RSZ 

SIS 

STV 



MACRO-32 
EXAMPLE 

$GET RAB ADDR 



Internal stream identifier. 

Record access mode. 

Record's address. (Used only if RAC = RFA.) 

Record-processing options. 

User record area address. 

User record area size. 

Record address. 

Record's file address. 

Record size. 

Completion status code. (Also returned in RO). 

Status value. (See Return Status, above.) 



BLISS-32 
EXAMPLE 

$GET (RAB=RAB_ADDR); 
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$DS_GETBUF 



The $DS_GETBUF macro is used to obtain buffer space. In standalone 
mode, the buffer space is allocated by the VDS from its free memory pool. 
In user mode, the VDS calls the VK/IS $EXPREG system service (see the 
WAXA/MS System Services Reference Manual for details). 

The caller indicates the number of pages desired, and the service returns 
the low and high addresses of the space allocated. 

When the program no longer needs the allocated buffer space, it can be 
returned to the free memory pool with the $DS_RELBUF macro. 



MACRO-32 $DS_GETBUF_x pagcnt, [retadr], [phyadr], [region] 



BLISS-32 



$DS_GETBUF (PAGCNT = pagcnt, 
[RETADR = retadr], 
[PHYADR = phyadr], 
[REGION = region]); 



ARGUMENTS 



pagcnt 

Size (number of pages) desired for buffer. 

retadr 

Address of a 2-longword array to receive the virtual addresses of the low 
and high buffer limits. 

phyadr 

Address of a 2-longword array to receive physical addresses of low and 
high buffer limits. This parameter is only relevant in standalone mode. 

region 

Memory region from which caller wishes buffer space to be allocated. 
Values are: 

0: buffer allocated from PO space (default). 
1: buffer allocated from PI space. 
2: buffer allocated from system space. 

In standalone mode, this parameter is only relevant if memory 
management is turned on. 
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RETURN 
STATUS 



SS$_NORMAL 
SS$_ACCVIO 

SS$_EXQUOTA 

SS$_ILLPAGCNT 
SS$_INSFWSL 

SS$_VASFULL 
RO =.0 



Buffer space allocated. 

The "retadr" array cannot be written by the caller. 
User mode only. 

The process exceeded its paging file quota. User 
mode only. 

Requested page count was less than 1 . 

The process's working set limit is not large enough 
to accommodate the increased virtual address 
space. User mode only. 

Insufficient virtual address space is available to fulfill 
the buffer request. (See Note 4.) 

Illegal value was given for "region" parameter. 
Standalone mode only. 



NOTES 



1 If PI space is requested in user mode, the "retadr" array will contain 
the allocated space's high address as its first element and the low 
address as its second element. 

2 In standalone mode, buffer space will always be allocated as contiguous 
pages. If there is not a set of contiguous pages equal to the requested 
buffer size, then the SS$_VASFULL stahis will be rehirned. 

3 In standalone mode, buffer space is allocated starting at the lowest 
available physical page. 

4 If there are fewer pages available than the number requested, then the 
number of pages available will be allocated. The beginning and ending 
virtual addresses of this area will be placed in the "retadr" array. 
When the number of available pages is 0, the "retadr" and "phyadr" 
arrays will contain address as the low and high buffer limits. 

5 Use the $DS_GETBUF service to allocate memory for an attached 
process when the code to be executed is in a separate file. (Use 
$DS_LOAD or RMS service to load the file into the buffer.) 

6 In a multiprocessor environment, use the primary processor to make 
all $DS_GETBUF (and $DS_RELBUF) calls. 
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IVIACRO-32 
EXAMPLE 

$DS_GETBUF_S #10, B0FLIMITS ;Ask for 10 pages. 



BLISS-32 
EXAMPLE 



$DS_GETBUF !Ask for 5 pages In PI space. 
(PAGCNT=5, 
RETADR-BUF_LIMI TS , 
REGI0N=1); 
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SGETCHN 



The Get I/O Channel Information system service returns information 
about a device to which an I/O channel has been assigned. Two sets of 
information can be returned: 

• The primary device characteristics 

• The secondary device characteristics 

In most cases, the two sets of characteristics are identical. However, there 
are three instances in which the primary and secondary characteristics are 
not the same: 

• If the device is associated with a mailbox, the primary characteristics 
are those of the device and the secondary characteristics are those of 
the mailbox. 

• If the device is a spooled device, the primary characteristics are those 
of the intermediate device and the secondary characteristics are those 
of the spooled device. 

• If the device is a logical link in a network, the secondary characteristics 
describe the link. 

If the diagnostic program is running in standalone mode, the primary and 
secondary characteristics will always be identical. 

This service is not available to level 3 programs. 

Note: It is recommended that all newly developed level 2R programs use the 

VMS $GETDVI service instead of $GETCHN, because of plans to remove 
support of $GETCHN from VMS. Refer the VAXA^MS System Services 
Reference Manual. 



MACRO-32 $GETCHN chan, [prilen], [phbuf], [scdlen], [scdbuf] 



BLISS-32 $GETCHN CHAN = chan, [PRILEN = prilen], 

[PRIBUF = pnbuf], [SCDLEN = scdlen], 
[SCDBUF = scdbuf] 
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ARGUMENTS 



Chan 

Number of the I/O channel assigned to the device. 

prtlen 

Address of a word to receive the length of the primary characteristics. 

pribuf 

Address of a character string descriptor (see Section 5.3) pointing to buffer 
that will receive primary characteristics. The default is 0, implying no 
buffer. 

scdien 

Address of a word to receive the length of the secondary characteristics. 

scdbuf 

Address of a character string descriptor (see Section 5.3) pointing to buffer 
that will receive secondary characteristics. The default is 0, implying no 
buffer. 



RETURN 
STATUS 



SS$_BUFFEROVF 

SS$_NORMAL 
SS$_ACVIO 

SS$JVCHAN 

SS$_NOPRIV 



Service successfully completed. Device information 
overflowed the buffer(s), so Information was 
truncated. 

Service successfully completed. 

A buffer descriptor cannot be read by the caller, or 
a buffer or buffer length cannot be written by the 
caller. User mode only. 

An invalid channel number was specified; that is, a 
channel number of or a number greater than the 
number of channels available. 

The specified channel is not assigned or was 
assigned from a more privileged access mode. 
User mode only. 
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NOTES 



1 In standalone mode, the device characteristics are placed into the 
specified buffer in the format illustrated in Figure 5-7. 

Figure 5-7 Device Characteristics Buffer (Standalone Mode) 
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DEVICE CHARACTERISTICS 


BUFFER SIZE 


TYPE 


CLASS 


DEVICE-DEPENDENT INFORMATION 




UNIT NUMBER 



ZK-«79&fl5 



Following the unit number is an ASCII string representing the device's 
generic name. 

The "device characteristics" and "device dependent information" 
fields are the same as they are for user mode. Refer to the VAX/VMS 
I/O User's Guide for details. 

In user mode, the device characteristics are placed into the specified 
buffers in the format detailed in the VAX/VMS I/O User's Guide. 

Refer to the VAX/VMS System Services Reference Manual for privilege 
restrictions and other notes on the use of this service in user mode. 



MACRO-32 








EXAMPLE 








CHANWOM: 


.WORD 







BUFFER; 










.LONG 


DIB$K 


LENGTH 




.LONG 


BBUF 




BBUF: 


.BLKB 


DIB$K 


LENGTH 



$GETCHN S CHANNUM, , BUFFER 
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BLISS-32 
EXAMPLE 



OWN 



CHANNUM : VECTOR [WORD], 

BBUF ! VECTOR [DIB$K_LENGTH, BYTE], 

BUFFER : VECTOR [2] 

INITIAL (DIB$K_LENGTH, BBUF), 



$GETCHN (CHAN=. CHANNUM, ,PRIBUF=BUFFER) ; 



5-198 



$DS_GETTERM 



$DS_GETTERM 



The Get Terminal Characteristics service can be used to obtain the type 
and characteristics of the user's terminal. 



MACRO-32 



$DS_GETTERM_x termchar 



BLISS-32 



$DS_GETTERM (TERMCHAR = termchar); 



ARGUMENTS 



termchar 

Address of a quadword to receive the terminal characteristics. See Note 1 
for the format of the characteristics. 



RETURN 
STATUS 



NOTES 



SS$_NORMAL 



Service successfully completed. 



1 The terminal characteristics are returned in a quadword with fields in 
Figure 5-8. 

Figure 5-8 Format of Terminal Characteristics 
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Values for the "type" field and "terminal characteristics" are defined 
by the $TTDEF macro of VMS. 

Note: In standalone mode, only the "tjrpe" and "terminal characteristics" 

fields are supplied. For terminal characteristics, only TT$M_SCOPE is 
provided. In user mode, all fields and all terminal characteristics are 
supplied. 
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MACRO-32 
EXAMPLE 

TERM_INPO: .BLKQ 1 



$DS GETTERM S TERM INFO 



BLISS-32 
EXAMPLE 



OWN 

TERM_INFO : VECTOR [ 2 ] ; 



$DS_GETTERM (TERM_CHAR=TERM_INFO) ; 
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$GETTiM 



The Get Time system service furnishes the current system time in 64-bit 
format. The time can be converted to ASCII by using the $ASCTIM service. 



MACRO-32 SGETTIM timadr 



BLISS-32 



$G ETTI M (TIMADR = timadr); 



ARGUMENTS 



timadr 

Address of a quadword that is to receive the current time in 64-bit format. 



RETURN 
STATUS 



SS$_NORMAL 
SS$_ACCVIO 



Service successfully completed. 

The quadword to receive the time cannot be written 
by the caller. User mode only. 



MACRO-32 
EXAMPLE 

$GETTIM S TIME 



BLISS-32 
EXAMPLE 

$GETTIM (TIMADR=TIME) ; 
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$DS_GPHARD 



The Get Hardware Parameter Table system service will provide the caller 
with the address of the p-tabie for the logical unit specified. The p-table's 
contents can then be accessed by the caller. The macro is used in a 
diagnostic program's initialization code, discussed in Section 3.5. 



MACRO-32 



$DS_GPHARD_x devnam, adrloc 



BUSS-32 



$DS_GPHARD_x (UNIT = devnam, RETADR = adrloc); 



ARGUMENTS 



devnam 

The logical unit number of the device whose p-table is being requested. 
Minin\um value is 0. Maximum value is determined by VDS, depending 
on the number of selected device imits testable by caller. (See notes.) 

adrloc 

Address of longword to receive p-table base address. 



RETURN 
STATUS 



SS$_NORMAL 
DS$_ERROR 



Service successfully completed. 

The argument list does not contain exactly two 
arguments. 

The specified logical unit number is too large. 



NOTES 



If "devnam" was initialized to and incremented after each issuance 
of the $DS_GPHARD macro, then the DS$_ERROR return status simply 
means that the p-tables for all selected, testable device units have been 
referenced. "Devnam" should be reinitialized to 0. See Section 3.5, 
Initialization Code, for details. 
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MACRO-32 
EXAMPLE 

INCL LOG_UNIT 
$DS_GPHARD_S - 

LOG UNIT, P_ TABLE 



BLISS-32 
EXAMPLE 

LOG_UNIT = .LOG_UNIT + 1; 

$DS~GPHARD (UNIT=.LOG_UNIT, RETADR=P_TABLE ) ; 
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$DS_HALTATTACHED 



Use the Halt Attached CPU system service to stop program execution in 
an attached processor in a muitiprocessor environment (exit the IDLE state 
and enter the HALT state, see Figure 4-8). In order to use this service, 
you must bootstrap the processor with the $DS_BOOTATTACHED service. 



MACRO-32 



$DS_HALTATTACHED_x unit 



BLISS-32 



$DS_HALTATTACHED (UNIT = unit); 



ARGUMENTS unit 



Logical unit number of the CPU to be halted. 



RETURN 
STATUS 



DS$_NORMAL 
DS$_ILLUNIT 
DS$JNVCPU 
DS$JNIT FAIL 



Service successfully completed. 

The specified logical unit number is too large. 

The specified processor is the primary processor. 

The processor failed to send console prompt 
(VAX 82XX/83XX only). 



NOTES 



1 In order to restart a halted processor, you must reboot 
using the $DS_BOOTATTACHED service and then use the 
$DS_STARTATTACHED service. 

2 Once you halt a processor, the EXAMINE and DEPOSIT commands are 
unavailable until you reboot using the $DS_BOOTATTACHED service. 

3 $DS_HALTATTACHED should be used in the clean-up code, to place 
each attached processor into a known, static state after testing. 
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MACRO-32 
EXAMPLE 



$DS HALTATTACHED_S LOG_UNIT 



BLISS-32 
EXAMPLE 

$DS_HALTATTACHED (UNIT 



,LOG_UNIT); 
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$DS_HEADER 



The $DS_HEADER macro generates the diagnostic program header. The 
header must be situated so that its starting address is virtual 512 (200 
hexadecimal). (The diagnostic program may not use address space below 
the header.) 



MACRO-32 



$DS_H EADER < pname >, rev, [update], [nunit] 



BLISS-32 



$DS_HEADER (PNAME= 'pname', REV=rev, 

[UPDATE = update], [NUNIT = nunit]); 



ARGUMENTS pname 

Character strmg representmg the program's name. This string is displayed 
on the user's terminal when the program is started. 

Note: In BLISS-32, if a (') character is to be included in the string, it must be 
included twice, as in PNAME = 'MARY"S PROGRAM'. 

The string should contain the following information: 

• The program's name (EVKAC, EVRAD, and so on) 

• The program's level (2, 2R, or 3) 

• The type of program (logic test, function test, or exerciser; see 
Chapter 1) 

• The types of devices that the program can test 
Refer to the examples below. 

rev 

Numeric value representing the program revision level. 

update 

Ntuneric value representing the program patch level. The default is 0. 

nunit 

Numeric value representing the maximum number of device units that can 
be tested by the program. The default is 0. 



NOTES 



1 Refer to the templates in Appendix A to determine the exact location 
of the $DS_HEADER macro in relation to other macros appearing in 
the program. The arrangement of macros depends on whether the 
program is written in MACRO-32 or BLISS-32. 
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MACRO-32 
EXAMPLE 



$DS_HEADER - 

<DZ11 8 LINE ASYNC MUX TEST>, REV = 01, UPDATE = 0, NUNIT 



BLISS-32 
EXAMPLE 



$DS_HEADER 

(PNAME = 'DZll 

$DS HEADER <DZ11 8 



L$L_HEADLENGTH : 

L$L~ENVIRON: 

L$A_NAME: 

L$L_REV! 

LSL_UPDATE: 

L$A~LASTAD: 

L$A_DTP: 

L$A_DEVP: 

LSL_UNIT: 

L$A~DREG! 

LSA_ICP: 

L$A CCP: 

LSA_REPP! 
L$A_STATAB: 
L$L_ERRTYP : 
L$A_TSTCNT! 
A_ HEADEND! 
T NAME! 



LASTAD! 



8 LINE ASYNC MUX TEST' 



REV 



LINE ASYNC MUX TEST>, REV 
.SAVE 

.PSECT $HEADER, PAGE, 
.LONG A_HEADEND -. 
. LONG $ENV 
.ADDRESS T_NAME 
.LONG 01 
. LONG 
.ADDRESS LASTAD 
.ADDRESS DISPATCH 
.ADDRESS AL_DEVTYP 
.LONG 8 

.ADDRESS DEV_REG 
. LONG [ 5 ] 
.ADDRESS INITIALIZE 
.ADDRESS CLEANUP 
.ADDRESS SUMMARY 
.ADDRESS 
. LONG 
.ADDRESS SECTION 



01, UPDATE = 0, NUNIT = 8 ) ; 
= 01, UPDATE = 0, NUNIT = 8 

NOEXE, NOWRT 

LENGTH OF HEADER DATA BLOCK. 

PROGRAM ENVIRONMENT. 

PROGRAM NAME TEXT ADDRESS. 

PROGRAM REVISION LEVEL. 

DIAGNOSTIC ENGR PATCH ORDER. 

FIRST FREE LOCATION AFTER PROGRAM. 

TEST DISPATCH TABLE POINTER. 

DEVICE TYPE LIST POINTER. 

NUMBER OF UNITS THAT CAN BE TESTED. 

DEVICE REGISTER CONTENTS TABLE POINTER. 



INITIALIZATION CODE POINTER. 

CLEAN-UP CODE POINTER. 

SUMMARY REPORT CODE POINTER. 

STATISTIC TABLE POINTER. 

# OF TYPES OF $ERRSOFT AND SERRHARD. 

LIST OF SECTION NAME ADDRESSES. 



.ASCIC \DZ11 8 LINE ASYNC MUX TEST/ 

.PSECT, _LAST, PAGE 

.PSECT, SYSTCNT, NOEXT, NOWRT, OVR, LONG 
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$DS_HELP 



The Display Help Text service can be used to display text contained in a 
iielp file. Help files are described in Chapter 6. This service is functionally 
identical to the VDS command HELP. 



MACRO-32 



$DS_HELP_x keylst 



BLISS-32 



$DS_HELP (KEYLST = keylst); 



ARGUMENTS 



keylst 

Address of a character strmg descriptor (see Section 5.3) that points to a list 
of help file keywords. This list is exactly equivalent to the ke3rwords that 
would be included as parameters to the HELP command (see the VAX/DS 
Diagnostic Supervisor User's Guide). To reference the help file EVXYZ.HLP, 
for diagnostic program EVXYZ, the first ke5rword in the list must be EVXYZ. 



RETURN 
STATUS 



The return status may be any status that may be returned from the $OPEN, 
$CONNECT, $READ, or $CLOSE services of RMS. Refer to descriptions of 
these services. 



MACRO-32 
EXAMPLE 



KEYSTRING : 



•ASCID /EVXYZ MANUAL OPTIONS/ 



$DS_HELP_S KEYSTRING 



BLISS-32 
EXAMPLE 



BIND KEYSTRING = UPLIT (%ASCID 'EVXYZ MANUAL OPTIONS'); 



$DS_HELP ( KEYLST-KEYSTRING ) ; 
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$DS^$HEX 



The $DS_$HEX p-table descriptor macro is used to read a value from 
tlie ATTACH command line, if no more parameters are available on the 
command line, or if the next parameter Is not a hex value, the user will be 
prompted with the prompt text value. The value that is read is left in the 
"value register" (see Section 3.2.3.3) for use by a $DS_$COMPLEMENT, 
$DS_$STORE, or $DS_$CASE statement. 



MACRO-32 



$DS_$HEX <prompt>, low, high 



BLISS-32 



$DS_$HEX (PROMPT = 'prompt', LOW = low, 
HIGH = high); 



ARGUMENTS 



prompt 

Character string that is to be printed as a prompt to the user. This prompt 
will be used if the ATTACH command line does not contain the required 
value. 

low 

The low limit for the value. If the value given is lower than this, an 
error message followed by the prompt message will be displayed. For 
MACRO-32, the default radix for this value is hexadecimal. For BLISS-32, 
the default radix is decimal. 

high 

The high limit for the value. If the value given is higher than this, an 
error message followed by the prompt message will be displayed. For 
MACRO-32, the default radix for this value is hexadecimal. For BLISS-32, 
the default radix is decin\al. 



NOTES 



1 Code generated by macro (shown in Macro-32; Bliss-32 is equivalent): 



.BYTE ^XBi 

.ASCIC \pronipt\ 

.LONG 'X<low> 

. LONG "X<high> 



Beginning of HEX prompt 
Prompt string 
Low limit 
High limit 
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$DS_$HEX 



MACRO-32 
EXAMPLE 



$DS_$HEX <WCS Last address>,0,FFFO 



BLISS-32 
EXAMPLE 

$DS_$HEX (PROMPT='WCS Last address', LOW=0, HIGH=%X ' FPFO ' ) ; 
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$HIBER 



The Hibernate system service aiiows a diagnostic program to mal<e 
itself inactive. A tiibernating program can be interrupted to process 
asynclironous events. After the diagnostic program's event handler has 
been executed, the program will be returned to its state of hibernation. 
This state will remain in effect until the program is awakened with the 
$WAKE system service. 



MACRO-32 



$HIBER_S 

Note: (Only the _S form of the macro is supported.) 



BLISS-32 



$HIBER; 



RETURN 
STATUS 



SS$_NORMAL 



Service successfully completed. 



NOTES 



III standalone mode, the only way for a hibernating program to be 
awakened is for an event handler (for example, an AST routine or 
interrupt service routine) to call the $WAKE service. 

In user mode, a hibernating process may be awakened by another 
process. Refer to the VAX/VMS System Sewices Reference fAanual for 
details. 

In a multiprocessing environment, $HIBER cannot be called from 
within a block of code delineated by the $DS_BGNATTACHED and 
$DS_END ATT ACHED macros. 



MACRO-32 
EXAMPLE 



$H1BER S 



BLISS-32 
EXAMPLE 



$HIBER; 
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$DS_HPEO„DECL 



The $DS_HPEO_DECL is used for BLISS-32 programs. 
Symbols defined are: 

HPEST_DEVICE - An ASCII string representing a device if in the 

name$ggan format . 
HPE$A_EPB - Address of the extended p-table block. 
HP$W_EXT_DRIVE - The unit number of the device. 



BLISS-32 
FORMAT 



$DS_HPEO_DECL ($DS_xxxx_DEF): 



ARGUMENTS 



$DS_xxxx_DEF 

"xxxx" represents the name of the device for which p-table fields are to be 
defined, such as $DS_HPEO_DECL ($DS_KA_DEF). 



NOTES 



These symbols should be used as offsets from the base of the extended 
p-table. The following code shows how to compute the address of the 
EPB. 



MOVL 


PTABLE,R2 


MOVZWL 


HP$WSIZE(R2) 


RDDL2 


R2,R3 


SUBL2 


#4,R3 


MOVL 


(R3),R4 



; Address of ptable in R2 

R3 ; Move size of p-table into R3 

; Compute end of extended p-table 

; Address of EPB stored here 

; Move address into R4 



Refer to Section 3.2.4, Referencing Extended P-Tables from a 
Diagnostic Program. 



BLISS-32 
EXAMPLE 

$DS_HPEO_DECL ( $DS_KA_DEF ) ; 
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$DS_HPEODEF 



The $DS_HPEODEF macro defines (for MACRO-32 programs) the 
symbolic names of the device-independent fields of an extended p-tabie. 

Symbols defined are: 

HPE$T_DEVICE - An ASCII string representing a device if in the 

name$ggan format. 
HPE$A_EPB - Address of the extended p-table block. 
HP$W EXT DRIVE - The unit number of the device. 



MACRO-32 
FORMAT 



$DS_HPEODEF [gbl] 



ARGUMENTS 



bl 

an be LOCAL or GLOBAL 



NOTES 



These symbols should be used as offsets from the base of the extended 
p-table. The following code shows how to compute the address of the 
EPB. 



MOVL 


PTABLE , R2 


MOVZWL 


HP$WSIZE(R2 


ADDL2 


R2,R3 


SUBL2 


#4,R3 


MOVL 


(R3),R4 



R3 



Address of ptable in R2 
Move size of p-table into R3 
Compute end of extended p-table 
Address of EPB stored here 
Move address into R4 



Refer to Section 3.2.4, Referencing Extended P-Tables from a 
Diagnostic Program. 



MACRO-32 
EXAMPLE 

$DS HPEODEF GLOBAL 
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$DS_HPO_DECL 



The $DS_HPO_DECL macro defines (for BLISS-32 programs) the 
sysmbolic names of the device-independent fields of a p-table. 

Symbols defined are: 



HP$Q 


DEVICE 


HP$W 


SIZE 


HP$B 


FLAGS 


HP$B 


DRIVE 


HPST 


DEVICE 


HP$A_DEVICE 


HPSA 


DVA 


HP$A 


LINK 


HP$W VECTOR 


HP$T 


TYPE 


HP$A 


DEPENDENT 



Quadword descriptor of device name 

Total length of p-table 

Initialization flags 

Unit number 

Start of device name string 

Hardware address of device 

Base of address space assigned to device 

Address of p-table for device's link 

Device's vector 

Start of counted string for device type 

Start of device-dependent portion of p-table 

Device-dependent fields 



BLISS-32 



$DS_HPO_DECL ($DS_xxxx_DEF); 



ARGUMENTS 



$DSjixxx_DEF 

"xxxx" represents the name of the device for which p-table fields are to be 
defined, such as $DS_HPO_DECL ($DS_KA_DEF). 



NOTES 



These S3mibols should be used as offsets from the base of the p-table. 
For example, if the p-table base address was placed in R2, the vector 
field could be referenced as HP$W_VECTOR(R2). Refer to Section 3.2.4, 
Referencing P-Tables from a Diagnostic Program. 



BLISS-32 
EXAMPLE 

$DS_HPO_DECL ($DS_KA_DEF) ; 
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$DS_HPODEF 



The $DS_HPODEF macro defines (for MACRO-32 programs) the symbolic 
names of the device-independent fields of a p-table. 

Symbols defined are: 

Quadword descriptor of device name 

Total length of p-table 

Initialization flags 

Unit number 

Start of device name string 

Hardware address of device 

Base of address space assigned to device 

Address of p-table for device's link 

Device's vector 

Start of counted string for device type 

Start of device-dependent portion of p-table 

Device-dependent fields 



HP$Q 


DEVICE 


HP$W 


SIZE 


HP$B 


FLAGS 


HP$B 


DRIVE 


HP$T 


DEVICE 


HP$A 


DEVICE 


HP$A 


DVA 


HP$A_ 


LINK 


HP$W 


VECTOR 


HP$T 


TYPE 


HP$A_ 


DEPENDENT 



MACRO-32 



$DS_HPODEF [gbl] 



ARGUMENTS gbl 



an be LOCAL or GLOBAL 



NOTES 



1 These symbols should be used as offsets from the base of the p- 
table. For example, if the p-table base address was placed in R2, the 
vector field could be referenced as HP$W_VECTOR(R2). Refer to 
Section 3.2.4, Referencing P-Tables from a Diagnostic Program. 



MACRO-32 
EXAMPLE 

$DS HPODEP GLOBAL 
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$DS.$INmALIZE 



The $DS„$INITIALIZE p-table descriptor macro must be the first macro in 
every p-table descriptor, it is used to indicate the device type, the p-table's 
total size, the maximum number of units allowed by the hardware, and the 
name of the device driver required for a level 2 diagnostic program to 
reference the device. 



MACRO-32 



$DS_$INITIALIZE device, length, max, driver 



BLISS-32 



$DS_$INITIALIZE (DEVICE = device, 

LENGTH = length, MAX = max, 
DRIVER = driver); 



ARGUMENTS 



cfeWce 

Character string representing the device iype of the hardware being 
described by the p-table, such as RK611, RK06, RM03, RH780, and so 
on. The string specified here will be the string that the user must type as 
the first argument to the ATTACH command, as in ATTACH RK611. 

length 

The length (in bytes) of the p-table that is to be created. The length 
includes both the device-independent and the device-dependent fields. 
Generally, a symbolic name for this value is created with a $DEF macro 
during memory allocation specifications, as illustrated in Section 3.2.2. 

max 

The maximum number of units that can exist. This number is controlled by 
the hardware design. For example, the number would be 8 for an RK07, 
since that is the maximum number of RK07 drives that can exist on an 
RK711 controller. 

Some devices, such as controllers and adapters, are not assigned a unit 
number. For these cases, "max" should be 0. If this value is greater 
than 0, and if the $DS_$NAME macro is not used, the device's generic 
name will be required to contain a unit number. If, on the other hand, the 
$DS_$NAME macro is used, then whether or not a unit number must be 
typed is controlled by the $DS_$NAME statement. 

The default value for "max" is 0. 

driver 

The name of the QIO driver (if any) needed by level 2 diagnostic programs 
in order to reference the device. The value must be a string of two 
characters. The string given, dn, determines the driver loaded as follows: 
the string is appended to the string EVQ and followed by the file type 
.EXE. Thus, the driver's filename is EVQdn.EXE. 
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$DS_$INITIALIZE 



NOTES 



1 Code generated by macro (shown in Macro-32; Bliss-32 is equivalent): 



.ASCIC \Device\ 

.BYTE Length 

.BYTE Max_Units 

.WORD ''A"Driver" 

.BYTE "X80 



ASCIC device type 

Length of p-table 

Maximum unit number 

Driver suffix 

End of initialization statement 



MACRO-32 
EXAMPLE 



$DS_$INITIALIZE 



$DS $INITIALIZE 



DEVICE=DMC11, - 
LENGTH=HP$K_DMC11_LEN, - 
DRIVER=<XM> 

DEVICE=DW7 80, - 
LENGTH=HP$K_DW7 8 0_LEN , - 
MAX=3 



$D5_$INITIALIZE RK611, HP$K_RK611_LEN, 



BLISS-32 
EXAMPLE 



$DS_$INITIALIZE (DEVICE-' DMCll ' , 

LENGTH=HP$K_DMC1 1_LBN , 
DRIVER='XM' ); 

$DS_$IKITIALIZE (DEVICE='DW780 ' , 

LENGTH=HP$K_DW7 80_LEN , 

MAX=3) ; 
$DS_$INITIALIZE (DEVICE='RK6H' , LENGTH=HP$K_RK611_LEN) ; 
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SDSJNITSCB 



The Initialize System Control Blocl< system service will load tiie VDS 
default values into all vectors within the SCB. It can be used to restore 
VDS exception and interrupt handling to all vectors if the diagnostic 
program has previously defined its own handlers using the $DS_SETVEC 
service. 

This system service is only available to level 3 diagnostic programs. 



MACRO-32 



$DSJNITSCB_x 



BLISS-32 



SDSJNITSCB; 



RETURN 
STATUS 



SS$_NORMAL 



Service successfully completed. 



NOTES 



1 In a multiprocessing environment, $DS_INITSCB only alters the SCB 
of the primary process. 



MACRO-32 
EXAMPLE 

$DS_INITSCB_S; 



BLiSS-32 
EXAMPLE 

$DS_INITSCB; 
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$DSJNLOOP 



The $DSJNLOOP program control macro can be used to determine 
if a program ioop is being executed. Program looping is discussed in 
Section 3.10. 



MACRO-32 $DSJNLOOP_x 



BLISS-32 



$DSJNLOOP; 



RETURN 
STATUS 



DS$_NORIVIAL 
DS$_ERROR 



A program loop is being executed. 
A program loop is not being executed. 



MACRO-32 
EXAMPLE 

$DS_INL00P_S 



BLISS-32 
EXAMPLE 

$DS_INLOOP; 
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$DS_LOAD 



The $DS_LOAD system service can be used for reading a file into a buffer 
area. This service may be employed when the full range of processing 
options provided by RMS is not needed. (The $DS_LOAD sen/ice uses 
RMS to implement its functionality.) 



MACRO-32 



$DS_LOAD_x file, default, length, address, retlen, 
retrec,[vbn] 



BLISS-32 



$DS_LO AD (FILE = file, DEFAULT = default, 

LENGTH = length, ADDRESS = address, 
RETLEN = retlen, RETREC = retrec, 
[VBN = vbn]); 



ARGUMENTS file 



Address of a quadword descriptor (see Section 5.3) describing a character 
string that represents the name of the file to be loaded. The filename 
format is: 

NODE::DEV:[DIRECTORY]FILENAME.EXT;VER. 

If any fields of the filename are missing, they will be filled in with fields 
specified by the "default" parameter. 

default 

Address of a quadword descriptor (see Section 5.3) describing a character 
string that represents the default fields for the filename. 

length 

Size, in b)?tes, of the buffer that will receive the file. 

address 

Address of the buffer that will receive the file. 

retlen 

Address of longword to receive the total length of the file. 



5-220 



$DS_LOAD 



tetrec 

Address of a longword to receive RMS file attributes of the file. The first 
word of the longword will contain the FAB MRS (maximum record size) 
field. The third byte will contain the FAB RFM (record format) field. The 
fourth byte will contain the FAB FSZ (fixed header size) field. Refer to the 
discussion of the $FAB macro for descriptions of these fields. 

vbn 

Virtual block number. This is the number of the first virtual block to be 
read. The default value is 1, which will cause reading to begin with the first 
block of the file. 



RETURN 
STATUS 



The $DS_LOAD service can rehirn any of the statuses associated with the 
$OPEN, $CONNECT, $READ, $DISCONNECT, or $CLOSE services of 
RMS. Refer to the descriptions of these services for lists of return stahises. 



NOTES 



MACRO-32 
EXAMPLE 



In a multiprocessing enviromnent, $DS_LOAD cannot be called from 
within a block of code delineated by the $DS_BGNATTACHED and 
$DS ENDATTACHED macros. 



NAMEDESC: ; Filename descriptor 

.LONG ; Store filename string length here. 

.LONG BUFF ; Address of filencune string 
.BLKB 30 ; Store filename here. 



BUFFS 
DEFDESC : 



.ASCID 



BUF_SIZE = 512 
BUFFER: .BLKB 
FILE_LENGTH: 

-LONG 
FILB_ATTRs 

.LONG 



; Default filename string descriptor 
/.EXE;0/ 

BUF SIZE 



$DS LOAD_S NAMEDESC, DEFDESC, #BUF_SIZE, - 

BUFFER , F ILE_LENGTH , PI LE_ATTR 
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BLISS-32 
EXAMPLE 



LITERAL 

BUF_SIZE =512; 

OWN 

BUFFER : VECTOR [BUF_SIZE, BYTE], 
BUFF : VECTOR [30, BYTE], ! Store filename here 
NAMEDESC: VECTOR [2] ! Filename descriptor 

INITIAL (0, 

BUFF), 
FILE_LENGTH : VECTOR, 
FILE_ATTR ! VECTOR; 



I Store filename string length here. 
! Address of filename string 



BIND 
DEFDESC = 

UPLIT (%ASCID '.EXE;0');! Default filename string descriptor 



$DS_LOAD (FILE=NAMEDESC, DEFAULT=DEFDESC , LENGTH=BUF_SIZE, 

ADDRESS=BUFFER, RETLEN=FILE_LENGTH, RETREC=FILE_ATTR) ; 
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$DS_$LITERAL 



This p-table descriptor macro is used to load a iiteral value into the value 
register. This value can then be manipulated by a $DS_$COMPLEMENT, 
$DS_$STORE, or $DS_$CASE statement. 



MACRO-32 $DS_$LITERAL lit 



BLISS-32 $DS_$LITERAL (LIT = lit); 



FORMAT 



Value (longword) to be loaded into the "value register" (see 
Section 3.2.3.3). 



NOTES 



1 Code generated by macro (shown in Macro-32; Bliss-32 is equivalent): 



.BYTE ''X86 
.LONG lit 



; Beginning of LITERAL 
; Literal value 



MACRO-32 
EXAMPLE 

$DS_$LITERAL LIT="XFF 
$DS $LITERAL '^0775 



BLISS-32 
EXAMPLE 

$DS_$I,ITERAI. (LIT=%X'FF'); 
$DS_$LITBRAL (LIT=%0'776 ' ) ! 
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$DS_$LOGICAL 



This p-table descriptor macro is used to read a "yes" or "no" response 
from an ATTACH command line. The expected response is one of the 
strings 'YES' or 'NO'. They may be abbreviated, and may be upper or 
lower case. The value register will be loaded with a if the response was 
"no," or with a 1 if the response was "yes." 



MACRO-32 



$DS_$LOGICAL <prompt_> 



BLISS-32 
FORMAT: 



$DS_$LOGICAL (PROMPT = 'prompt'); 



ARGUMENTS 



prompt 

A character string represertting the prompting message to be displayed by 
the ATTACH command processing routine of the VDS. 



NOTES 



Code generated by macro (shown in Macro-32; Bliss-32 is equivalent): 



.BYTE -^XSB 
.ASCIC \prompt\ 



; Beginning of LOGICAL prompt 
; Prompt string 



MACRO-32 
EXAMPLE 

$DS $LOGICAL <Load WCS > 



BLISS-32 
EXAMPLE 

$DS_$LOGICAL (PROMPT='Load WCS'); 
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$DS.MEMSIZE 



The $DS_MEMSIZE macro returns the size, in pages, of physical memory. 
This macro cannot be called if you are running in user mode. 



MACRO-32 $DS_IVIEMSIZE_x memsiz 



BLISS-32 $DS_IVIEMSIZE (MEMSIZE = memsiz); 



ARGUMENTS memsiz 

Address of the longword to receive the number of pages of physical 
memory. 



RETURN 
STATUS 



SS$_NORMAL 
DS$_NOSUPPORT 



Service successfully completed. 

VDS Is running under VMS. Service is not supported 
online. 



MACRO-32 
EXAMPLE 

PAGE COUNT: .BLKL 1 



$DS MEMSIZE S PAGE COUNT 



BLISS-32 
EXAMPLE 



OWN 



PAGE_COUNT ! VECTOR; 



$DS_MEHSIZE (MEMSIZ=PAGE_COUNT) ; 
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$DS^MMOFF 



The Turn Memory Management Off (DS$_MMOFF) system service is 
provided for disabling tiie memory management hardware in standalone 
mode. 

Only level 3 diagnostic programs may disable memory management on or 
off. If a level 3 program disables memory management on or off, it must 
use this service to do so. 

Memory management is discussed in Section 4.3, Memory Management 
and Allocation. 



IVIACRO-32 



$DS_MMOFF_x 



BLISS-32 



$DS_MMOFF; 



RETURN 
STATUS 



SS$_WASCLR 
SS$_WASSET 
DS$_WARNING 



Service successfully completed. Memory 
management was previously disabled. 

Service successfully completed. Memory 
management was previously enabled. 

The $DS_MMOFF macro was Issued, but memory 
management was not disabled because a SET MM 
ON user command had previously been Issued (see 
the VAX/DS Diagnostic Supervisor User's Guide.) 



NOTES 



1 The user command SET MM ON has precedence over the 
$DS_MMOFF macro. Thus, a program cannot shut off memory 
mcmagement if the user has turned it on. 

2 In a multiprocessing environment, $DS_MMON and $DS_MMOFF 
cannot be called from within a block of code delineated by the 
$DS_BGNATTACHED and $DS_ENDATTACHED macros. 

Additionally, the primary processor cannot call $DS„MMON or 
$DS_MMOFF after an attached processor has been booted with the 
$DS_BOOTATTACHED service. 



MACRO-32 
EXAMPLE 



$DS MMOFF S 



;Turn off memory management. 
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$DS_MMOFF 



BLISS-32 

EXAMPLE (This example illustrates the case of a program that cannot execute if 

memory management is enabled. If the program cannot turn memory 
management off, it aborts.) 

! Turn off memory management. If the user has turned it on, 

1 call routine to report the problem, then abort the program. 

$DS_MMOFF; 

IF DS$_WARNING 

THEN 

BEGIN 

REPORT_MM_ON ( ) ; 

$DS_ABORT~ ( ) ; 

END; 
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$DS_MMON 



The Turn Memory Management On (DS$_MMON) system service is 
provided for enabling tlie memory management liardware In standalone 
mode. 

Only level 3 diagnostic programs may enable memory management. If a 
level 3 program enables memory management, it must use this service to 
do so. 

Memory management is discussed In Section 4.3, Memory Management 
and Allocation. 



MACRO-32 



$DS^MMON_x 



BLISS-32 



$DS_MMON; 



RETURN 
STATUS 



SS$_WASCLR 
SS$_WASSET 



Service successfully completed. Memory 
management was previously disabled. 

Service successfully completed. Memory 
management was previously enabled. 



NOTES 



The user command SET MM ON has precedence over the 
$DS_MMOFF macro. Thus, a program cannot shut off memory 
management if the user has turned it on. 

In a multiprocessing environment, $DS_MMON and $DS_MMOFF 
cannot be called from within a block of code delineated by the 
$DS_BGNATTACHED and $DS_ENDATTACHED macros. 

Additionally, the primary processor cannot call $DS_MMON or 
$DS_MMOFF after an attached processor has been booted with the 
$DS_BOOTATTACHED service. 



MACRO-32 
EXAMPLE 



$DS MMON S 



;Turn on memory management. 
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BLISS-32 

EXAMPLE (This example illustrates the case of a program that cannot execute if 

memory management is enabled. If the program cannot turn memory 
management off, it aborts.) 

! Turn off memory management. If the user has turned it on, 

! call routine to report the problem, then abort the progreim. 

$DS_MMOFF; 

IF DS$_WARNING 

THEN 

BEGIN 

REP0RT_MM_0N ( ) ; 

$DS_ABORT~ ( ) ; 

END; 



5-229 



$DS_$NAME 



$DS_$NAME 



The $DS_$NAME p-table descriptor macro is used if device name 
validation is desired, if used, thie macro must immediately follow tiie 
$DS_$INITIALIZE macro. Wlien this macro is present, the device generic 
name (the third argument to the ATTACH command) must conform to the 
naming conventions specified. (See note 1 for exceptions.) 

Ail device names can be described by the general formula 'ggan'; where 
'gg' Is a generic device prefix (not necessarily only two characters), 'a' 
is a letter representing which controller or bus adapter the device is on, 
and 'n' represents the device's unit number on that controller or adapter. 
Both the 'a' and 'n' portions are optional, but every device must have 
a 'gg' portion. For most devices, 'gg' is fixed by the physical type of 
the device; or. It may be determined by its LINK device (the controller to 
which it is attached). The $DS_$NAME statement allows specification and 
enforcement of these rules. 



MACRO-32 



$DS_$NAME flags, generic 



BLISS-32 $DS_$NAME (FLAGS = flags. GENERIC = generic); 



ARGUMENTS flags 



Flag bits that control the format of the device name. Symbolic names for 
the flags are defined by the $DS_PTDDEF macro. The flag bits are: 

• Bit — PTD$M_UNIT — The 'n' portion of the generic name is 
required for this device. Its maximum value is specified by the "max" 
parameter of the $DS_$INITIALIZE macro. 

• Bit 1 - PTD$M_CONTROLLER - The 'a' portion of the generic name 
is required for this device. If the bit PTD$M_INHERIT_CON is also set, 
the 'a' portion must match the 'a' portion of the controller to which 
this device is attached. 

• Bit 2 — PTD$M_NAME — Only the 'gg' portion of the generic name is 
required. This is most common for network devices, which are known 
by their DECnet names (for example, YODA, STAR, GALAXY). 

• Bit 3 - PTD$M_INHERIT_PRE - The 'gg' device name prefix is 
inherited from the controller to which the device is attached. This, for 
example, allows a VTIOO to require a name of the form 'TTan' when 
attached to a DZll ('TTa'), or 'TXan' when attached to a DMF32A 
('TXa'). 

• Bit 4 - PTD$M_INHERIT_CON - The 'a' controller designator 
portion of the device name is inherited from the controller to which the 
device is attached. This, for example, allows a VTIOO to require a name 
of the form 'TTAn' when attached to DZll 'TTA', or 'TTBn' when 
attached to DZll 'TTB'. 
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$DS_$NAME 



• Bits 5 to 7 are reserved for future expansion and must not be set by any 
p-tabie descriptor. 

Additionally, several special names are defined that combine common sets 
of these flag bits. They are: 

• PTD$M_INHERIT - This combines the bits PTD$M_INHERIT_PRE 
and PTD$M_INHERIT_CON. This is the normal permutation of the two 
bits. 

• PTD$M_DEVICE - This combines the bits PTD$M_CONTROLLER 
and PTD$M_UNIT. It would commorUy be used for devices that are 
connected directly to a bus, rather than a controller, and therefore 
require both 'a' and 'n' portions but should not inherit them from 
their LINK device. 

• PTD$M_ENDDEVICE - This combines the bits 
PTD$M_CONTROLLER, PTD$M_UNIT, and PTD$M_INHERIT. It 
would commonly be used for devices that have controllers, such as an 
RK07 that is attached to an RK711, and should inherit the controller's 
name prefix and controller letter. 

The default is PTD$M_DEVICE. 

generic 

The 'gg' portion required for this device. If the flag PTD$M_INHERIT_PRE 
is set, this argument is used only if the device is linked to HUB. 



NOTES 



1 The naming conventions specified with the $DS_$NAME will be 
ignored if the VDS is running under APT, or if the VDS is executing a 
script file. This is to ensure compatibility with APT scripts and VDS 
scripts that do not adhere to proper naming conventions. 

2 Code generated by macro (shown in Macro-32; Bliss-32 is equivalent): 



.BYTE '^X8D 
.BYTE flags 
•ASCIC "generic" 



Start of NAME statement 
Generic name format flags 
Enforced generic name 



MACRO-32 
EXAMPLE 

$DS_$NflME FLAGS=PTD$M_ENDDEVICE, GENERIC=DM 
$DS_$NAME PTD$M_UNIT, DM 
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BLISS-32 
EXAMPLE 

$DS_$NAME (FLAGS=(PTD$M_ENDDEVICE), GENERIC=' DM' ) ; 
$DS_$NAME (FLAGS=(PTD$M_UNIT), GENERIC='KA' ) ; 
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$DS_$OCTAL 



The $DS_$OCTAL p-table macro is used to read a value from the ATTACH 
command line. If no more parameters are available on the command line, 
or if the next parameter is not an octal value, the prompting message 
will be displayed to the user. The value that is read is stored in the 
"value register" (see Section 3.2.3.3) for use by a $DS_$COMPLEMENT, 
$DS_$STORE, or $DS_$CASE statement. 



MACRO-32 



$DS_$OCTAL prompt, low, high 



BLISS-32 



$DS $OCTAL (PROMPT = prompt, LOW = low, 
HIGH = high); 



ARGUMENTS 



prompt 

Character string that is to be printed as a prompt to the user. This prompt 
will be used if the ATTACH command Ime does not contain the required 
value. 

low 

The low limit for the value. If the value given is lower than this, an 
error message followed by the prompt message will be displayed. For 
MACRO-32, the default radix of this value is octal. For BLISS-32, the 
default radix is decimal. 

high 

The high limit for the value. If the value given is higher than this, an 
error message followed by the prompt message will be displayed. For 
MACRO-32, the default radix of this value is octal. For BLISS-32, the 
default radix is decimal. 



NOTES 



1 Code generated by macro (shown in Macro-32; Bliss-32 is equivalent): 



BYTE 


^X83 


; Beginning of OCTAL prompt 


ASCIC 


\prompt\ 


; Proinpt string 


LONG 


'"Clow 


; Low limit 


LONG 


'^Ohigh 


; High limit 
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MACRO-32 
EXAMPLE 

$DS_$OCTAL CSR, 760000, 777776 

$DS_$OCTAL PROMPT=<VECTOR_>, L0W=2 , HIGH=776 



BLISS-32 
EXAMPLES 



$DS_$OCTAL (PROMPT='CSR', LOW=%0' 760000' , HIGH=%0' 777776 ') ; 
$DS_SOCTAL (PROMPT=' VECTOR', L0W=%0'2', HIGH=%0' 776 ' ) ; 
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The Open Existing File service of RIVIS is used to mal<e a file available for 
processing. Opening a file is the first step in processing the information 
within the file. This service uses parameters within the FAB to determine 
which file to open and what access attributes to assign to the file. 



MACRO-32 



$OPEN fab, [err], [sue]; 



BLISS-32 



$OPEN (FAB = fab, [ERR = err], [SUC = sue]); 



ARGUMENTS fab 



RETURN 
STATUS 



Address of the FAB. The FAB is declared using the $FAB macro. 

err (user mode only) 

Address of routine to execute on error return from open service. 

sue (user mode only) 

Address of routine to execute on successful return from open service. 



RMS$_NORMAL 

RMS$_ACC 

RMS$_DME 

RMS$_DEV 
RIVISS.FAB 
RMS$_FNF 
RMS$_FNM 
RMS$_ORG 

RMS$_RER 



Service successfully completed. 

Error accessing file. 

Dynamic memory exhausted. Insufficient dynamic 
memory available. 

Bad device specification. 

Error in FAB. 

File not found. 

Bad file name. 

Invalid file organization. In standalone mode, file 
organization must be sequential. 

File read error. 



Note: For further details on return status values, refer to the VAX-U RMS 
Reference Manual. 



NOTES 



Table 5-6 lists the FAB fields used by the $OPEN service IN 
STANDALONE MODE. For user mode, refer to the VAX-11 RMS 
Reference Manual. 
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Tabfe 5-6 FAB Fields Used by $OPEN (Standalone Mode) 



Field Mnemonic 


Field Name 


Input: 




DNA 


Default file specification string address. 


DNS 


Default file specification string size. 


FAC 


File access. 


FNA 


File specification string address. 


FNS 


File specification string size. 


FOP 


File processing options. 


FSZ 


Fixed control area size; unit record devices only. 


IFI 


Internal file identifier (must be 0). 


RAT 


Record attributes (unit record devices only). 


RFM 


Record format; unit record devices only. 


XAB 


Extended attribute blocl< address. 


Output: 




ALQ 


Allocation quantity; contains the highest numbered block 
allocated to the file. 


BLS 


Block size. 


DEV 


Device characteristics. 


FSZ 


Fixed control area size; applies only to "variable with fixed 
length" control records 


IFI 


Internal file identifier. 


MRS 


Maximum record size. 


ORG 


File organization. 


RAT 


Record attributes. 


RFM 


Record format. 


STS 


Completion status code (also returned in RO). 





MACRO-32 
EXAMPLE 

$OPEN FAB BLOCK 



BLISS-32 
EXAMPLE 

$OPEN (FAB=FAB_BLOCK); 
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$DS^PAGE 



The $DS_PAGE macro is used in conjunction with the $DS_SBTTL macro. 
If the $DS_PAGE macro with a nonzero argument is placed immediately 
before the $DS_SBTTL macro, the following actions will taice place: 

• Printing of the $DS_SBTTL call in the assembly listing will be 
suppressed, but the expansion of the $DS_SBTTL macro will be 
printed. 

• The subtitle will appear at the top of a new page. 

The result of these actions is that the SBTTL statement accompanying 
text generated by the $DS_SBTTL macro will appear at the top of the next 
page in the assembly listing. 



MACRO-32 



$DS_SBTTL nam 



BLISS-32 



Not supported for BLISS-32. 



ARGUMENTS num 



Flag indicating whether or not the subtitle generated by the $DS_SBTTL 
macro should appear on a new page. If this value is 0, the subtitle will 
appear on the current page, and printing of the $DS_SBTTL macro call 
will be suppressed. If the value is nonzero, a new page will be started. 
The subtitle will appear at the top of the new page, and printing of the 
$DS_ SBTTL macro call will be suppressed. 



EXAMPLES 



$DS_PAGE 1 

$DS~SBTT!L <READ/WRITE TESTS> 
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$DS_PARDEF 



The $DS_PARDEF macro defines (for MACRO-32 programs) symbolic 
names for values that can be used with the "radix," "defalt," and 
"exword" parameters to the $DS_ASKxxxx macros. For BLISS-32 
programs, these symbols may be referenced without first issuing the 
$DS_PARDEF macro. 

Symbols defined are: 



PAR$_BIN 
PAR$_DEC 

par$Ihex 

PAR$_OCT 




par$_no 

PAR$~YE5 




PAR$V_NODEF 
PAR$V_ATLO 
PAR$V_ATHI 
PAR$V_ATDEF 


PAR$M_NODEF 
PARSM_ATLO 
PAR$M_ATHI 
PARSM ATDEF 



MACRO-32 



$DS_PARDEF [gbl] 



ARGUMENTS gbl 

Can be LOCAL or GLOBAL 



MACRO-32 
EXAMPLE 

$DS PARDEF GLOBAL 



5-238 



$DS_PARSE 



$DS_PARSE 



The Parse Command String system service can be used in a diagnostic 
program for wliicli a unique command language has been defined (see 
Section 4.2.2.2, Prompting the User). This service will parse a command 
string by searching a predefined command tree, iool<ing for a matches 
between the command string and nodes of the tree. Every time a match 
is found, the service will dispatch to an "action routine." Details are 
presented in the notes below. 



MACRO-32 



$DS_PARSE_x bufadr, tree, action 



BLISS-32 



$DS_PARSE (BUFFER = bufadr, TREE = tree, 
ACTION = action); 



ARGUMENTS 



bufadr 

Address of a quadword descriptor (see Sectioii 4.3) pointing to the 
command string. 

tree 

Address of the tree of valid commands. This tree should be defined by 
using the $DS_CLI macro. 

action 

Address of action routine. See notes for routine format. 



RETURN 
STATUS 



SS$_NORMAL 
DS$_ERROR 



Service successfully completed. 

While traversing the command tree, an error 
node (defined by CLI$K_ERROR, see $DS_CLI 
description) was encountered. In other words, an 
Illegal command string was specified. 



NOTES 



The command string to be parsed should be fetched from the user by 
issuing the $DS_ASKSTR macro. 

The $DS_PARSE system service wiU traverse the parse tree until a 
CU$K_EXIT or a CU$K_ERROR code is encountered (see DS$_CU 
description), at which point it will return to the caller. 
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3 As the tree is traversed, the action routine will be called each time 
there is a match between the contents of the current node of the tree 
and the input stream. If a match is found, the action routine is called 
and then the next node in the current path is checked. Otherwise, a 
branch to the node specified by the "miss" parameter of the $DS_CLI 
macro occurs. 

4 In a multiprocessing environment, $DS_PARSE cannot be called from 
within a block of code delineated by the $DS_BGNATTACHED and 
$DS_ENDATTACHED macros. 

Action Routines: 

Parameters will be passed to the action routine as follows: 

• RO — Will contain action code specified for current node in parse tree. 

• R7 — Will contain current value of pointer used by VDS when 
traversing tree. 

• R8 — Will point to next unparsed character in the input string. 

• R9 — Will contain number of unparsed characters remaining in input 
string. 

• RIO and Rll — Will contain quadword value of last numeric string read 
from input buffer. 

Generally, the programmer will specify a unique action code for each 
tree node, using the $DS_CLI macro. Sometimes a "null" action code 
is used, because it is not necessary for the action routine to do anything 
for nodes which do not completely identify a command, parameter, or 
qualifier. In other words, it is usually necessary to perform an action 
only when the parser is sure it has found something recognizable. When 
the action routine is called, the action code is passed in RO. The action 
routine can thus use a MACRO-32 CASE instruction or a BLISS-32 CASE 
expression, or some other means, to dispatch to a unique subroutine for 
each code. These subroutines will often just set bits in a bitmap indicating 
what command, command parameter, or command qualifier has been 
parsed. When the entire command string has been parsed, a command 
dispatching routine can be called. This dispatcher can examine the bitmap 
to determine which command processing routine to call. 
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An example action routine corresponding to the sample parse tree defined 
in the description of the $DS_CLI macro (earlier in this chapter) would be 
as follows: 



ACTION_RTN: : 




CASEL 


RO, #0, #8 


10$: 






. WORD ACT_NO_ACT I ON- 1 $ 




.WORD ACT_ADD-10$ 




.WORD ACT~BAKE-10$ 




.WORD ACT_BEAT-10$ 




.WORD ACT_MILK-10$ 




.WORD ACT~SALT-10$ 




.WORD ACT~SUGAR-10$ 




. WORD ACT_ I LLCMD- 1 $ 




.WORD ACT_BADARG-10$ 


ACT_NO_ACTION: 




RSB 




ACT_ADD: 




BISB 


#19ADD, CMD_BL0CK 


RSB 




ACT_BAKE: 




BISB 


#1@BAKE, CMD_BLOCK 


RSB 




ACT_BEAT ! 




BISB 


#1§BEAT, CMD_BLOCK 


RSB 




ACT_MILK! 




BISB 


#1@MILK, PARAM_BLOCK 


RSB 




ACT_SALT! 




BISB 


# IS SALT, PARAM_ BLOCK 


RSB 




ACT_ SUGAR: 




BISB 


♦ISSUGAR, PARAM_BLOCK 


RSB 




ACT_ir.LCMD: 




BISB 


tlglLLCMD, ERROR_BLOCK 


RSB 




ACT_BADARG; 




BISB 


#19BADARG, ERROR_BLOCK 


RSB 





5-241 



$DS_PARSE 



MACRO-32 
EXAMPLE 



This example fetches a command string, attempts to parse the string, and 
then either calls a command dispatcher or an error handler. 



$DS_ASKSTR_S - 

MSGADR=PROMPT_MSG , 
BUFADR=STRING_BUF 
CMPL RO, SS$_NORMAL 
BNEQ ASK ERRHNDLR 



MOVZBL 
MOVAL 



STRING_BUF, CMD_BUFFER 
STRING~BUF+1, CMD BUFFER+4 



$DS_PARSE_S - 

BUFADR=CMD_BUFFER, - 
TREE=TREE_ROOT , - 
ACT I ON=ACT I ON_RTN 
CMPL RO, SS$_NORMAL 
BNEQ PARSE ERRHNDLR 



BSBW 



CMD DISPATCHER 



; Prompt user for input string. 



; If error occurred 

; then go to error handler 

; Put string length and string 

; address in quadword descriptor 

; Parse the input string. 



; If unsuccessful parse 
; then go to error handler 

; Good parse - process command. 
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$DS^PRINTB 



The Format and Print ASCII Message system services provide a means by 
wiiicii complex messages can be formatted into ASCIi character strings 
and displayed on the user terminal. The macros that call these services 
are commonly referred to as the "print" macros. These macros can be 
used to 

• Insert variable character string data into an output string 

• Convert binary values into the ASCIi representations of their decimal, 
hexadecimal, or octal equivalents and substitute the results in an 
output string 

The system services construct an output string by referring to formatted 
ASCII output (FAQ) directives contained in a "control string" and using 
those directives to operate on the contents of value parameters. 

Once the system sen/ice creates the output string, it is automatically 
displayed on the user terminal. 

The $DS_PRINTB macro ("print basic error message") is used exclusively 
to display the second message level of error messages (see Section 3.9, 
Reporting Errors). Display of messages generated with this macro will be 
Inhibited if either of the VDS control flags IE2 or IE3 is set (see the VAX/DS 
Diagnostic Supervisor User's Guide). 



MACRO-32 



$DS PRINTB.x format, [pO], [p1], [p2l [p3], [p4J, 

[p5]. [p6], lp7l [p8J, [p9]. [pal [pb], 
[pc], [pd], [pel [pfj 



BLISS-32 



$DS_PRINTB (format, [pOl [p1l [p2l [p3l [p4l [p5l [ 
p6l [p7l [pdl [p9l [pal [pbl [pel [pdl 
[pel [pf]): 



ARGUMENTS 



format 

Address of a counted ASCII string. This is the "control string," which 
consists of the fixed text of the output string plus FAO directives for 
formatting variable data. FAO directives are listed below. Variable data is 
passed in parameters pO through pf . 

pO through pf 

to 16 directive parameters, contained in longwords. Depending on the 
corresponding FAO directive, a parameter may be a value that is to be 
converted, the address of a string that is to be inserted, a length, or an 
argument count. Parameters are listed in the order they are referenced by 
the control string. 
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RETURN 
STATUS 



NOTES 



SS$_NORMAL 
SS$_BUFFEROVF 

SS$_BADPARAM 



Service successfully completed. 

Service successfully completed, but the size of the 
output string was greater than the maximum allowed 
and was truncated (see notes). 

An invalid FAO directive was specified in the control 
string. 



1 VDS stores the output string in an internal buffer as it is being created. 
This buffer can contain up to 512 characters. If the output string is 
greater than 512 characters, the string is truncated and the truncated 
message is displayed. 

2 If it is necessary to format a message containing more than 16 
parameters, it is possible to 

• Use several PRINT macros in succession, or 

• Use the $FAO or $FAOL macros to format the message. The 
message should then be printed using the proper print macro (for 
example, PRINTX for a level 3 error message). 

3 In MACRO-32, the $FAO_S macro form uses a PUSHL instruction 
for all parameters (pi through pn) specified with the macro call. In 
other words, all arguments are assumed to be values, not addresses. 
Therefore, if an address is desired, precede the argument with a # 
character, or load the address into a register. 

4 In a multiprocessing environment), $DS_PRINTxxx cannot be called 
from within a block of code delineated by the $DS_BGNATTACHED 
and $DS_ENDATTACHED macros. 

5 An FAO directive has the following format: 
!DD 

where 

! indicates that the following character is to be interpreted as an FAO 

directive, and 

DD is a 1- or 2-character FAO directive. A directive requires a parameter 

to be included in the parameter list of the macro call. 

Note that all directives must be specified in uppercase letters. 

Optionally, a directive may include: 

• A repeat count, which has the following format: 

!n(DD) 

where n is a decimal number that indicates that the directive should 
be repeated for the next n parameters. 
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• An output field length, which has the following format: 

•lengthDD 

where length indicates the field length that the output resulting 
from the specified directive should have. 

• Both a repeat count and an output field length: 

!n(lengthDD) 

Repeat counts and output field lengths may be specified as 
variables by using a pound sign ( # ) in place of an absolute numeric 
value. If a pound sign (#) is specified for a repeat count, the next 
argument included in the macro call must contain the count. If 
a pound sign ( # ) is specified for an output field length, the next 
argument must contain the length value. If an output field length 
is specified as a variable, and a repeat count is also specified 
(by variable or by value), then only one length parameter will be 
fetched from the argument list, and each output string generated by 
the repeat count will have that length. 

A control string may be any length and may contain any number 
of FAO directives. The only restriction is on the use of the 
exclamation point (!) character (ASCII code 'X21). If a literal 
exclamation point (!) is required in the output string, the directive 
double exclamation points (!!) must be used. Each character in the 
control string that is not part of an FAO directive is copied into the 
output string. Thus, if a portion of the message being formatted is 
a nonvolatile character string, that string can be placed directly into 
the control string. If an invalid FAO directive is encountered in the 
control string, creation of the output string ceases at that point and 
an error status is returned to the caller. 

No tests are made to determine if the correct number of parameters have 
been included in the macro call. If fewer parameters have been specified 
than are referenced by the control string, the system service routine will 
continue to fetch parameters past the end of the parameter list. 

Table 5-7 lists the FAO directives. 

Table 5-8 summarizes how the length of each field in the output string is 
determined, if no field length has been specified. 
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Table 5-7 FAO Directives 



Directive 


Function 


Parameter(s) 


Character String Substitution: 


!AC 


Inserts a counted ASCII 


Address of the string; the first byte 




string. 


must contain the length 


!AD 


Inserts an ASCII string. 


1) Length of string 

2) Address of string 


!AF 


Inserts an ASCII string. 


1) Length of string 




Replaces all nonprintable 


2) Address of string 




ASCII codes with periods 
(■)■ 




!AS 


Inserts an ASCII string. 


Address of quadword 
character string 
descriptor pointing 
to the string 


Numeric Conversion (zero-filled): 


!0B 


Converts a byte to octal. 


Value to be converted to 


!OW 


Converts a word to octal. 


ASCII representation 


!0L 


Converts a longword to 
octal. 




!XB 


Converts a byte to 


For byte or word conversion, FAO 


!XW 


hexadecimal. 


uses only the low-order byte or 


!XL 


Converts a word to 

hexadecinnal. 

Converts a longword to hex. 


word of the longword parameter. 


IZB 


Converts an unsigned 




!ZW 


decimal byte. 




!ZL 


Converts an unsigned 





decimal word. 
Converts an unsigned 
decimal longword. 



Numeric Conversion (blank-filled): 


lUB 


Converts an unsigned 


Value to be converted to ASCII 


!UW 


decimal byte. 


representation 


lUL 


Converts an unsigned 
decimal word. 
Converts an unsigned* 
decimal longword. 




ISB 


Converts a signed decimal 


For byte or word conversion, FAO 


iSW 


byte. 


uses only the low-order byte or 


ISL 


Converts a signed decimal 

word. 

Converts a signed decimal 

longword. 


word of the longword parameter 
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Table 5-7 (Cont.) FAO Directives 



Directive 



Function 



Parameter(s) 



Output String Formatting: 



!/ 



%S 



!%T 



mo 

!n< 
1> 



!n*c 



Inserts new line (cr/lf). 

Inserts a tab. 

Inserts a form feed. 

inserts an exclamation point. 

Inserts the letter S if most 
recently converted numeric 
value is not 1 . 

Inserts ttie system time. 



Inserts tlie system date and 
time. 

Defines output field width of 
n. characters. All data and 
directives within delimiters 
are ieft-justified and blank- 
filled within the field. 

Repeats the specified 
character in the output string 
n times. 



None 



Address of a quadword time value 
to be converted to ASCII. If is 
specified, the current system time 
is used. 



None 



Parameter Interpretation: 



! + 



Reuses last parameter In the None 
list. 

Skips next parameter in the 
list. 



Note: If a variable repeat count and/or a variable output field length is specified 
with a directive, parameters indicating the count and/or length must 
precede other parameters required by the directive. 
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Table 5-8 FAO Field Lengths and Fill Characters 



MACRO-32 
EXAMPLE 







Action When 


Action When 






Explicit 


Explicit 






Output Field 


Output Field 


Conversion or 




Length is 


Length Is 


Substitution 


Default Length 


Longer Then 


Shorter Than 


Type 


of Output Field 


Default 


Default 


How FAO Determines Output Field Lengths and Fill Characters: 


Hexadecimal 


2 (zero-filled) 


ASCII result is 


ASCII result is 


byte 


4 (zero-filled) 


right-justified and 


truncated on the 


word 


8 (zero-filled) 


blank-filled to the 


left. 


longword 




specified length. 




Octal 


3 (zero-filled) 


Hex or octal output 




byte 


6 (zero-filled) 


is zero-filled to the 




word 


11 (zero-filled) 


default output field 




longword 




length, then blank- 
filled to specified 
length. 




Signed or 


As many 


ASCII result is 


Signed and 


unsigned 


characters as 


right-justified and 


unsigned decimal 


decimal 


necessary 


blank-filled to the 


output fields are 






specified length. 


completely filled 
with asterisks ( ' ). 


Unsigned 


As many 


ASCII result Is right- 




zero-filled 


characters as 


justified and zero- 




decimal 


necessary 


filled to the specified 
length. 




ASCII string 


Length of input 


ASCII string is left- 


ASCII string is 


substitution 


character string 


justified and blank- 


truncated on the 






filled to the specified 


right. 






length. 







The following examples will display this message: 



BYTES TRANSFERRED; xxxxxxxx BAD; yyyyyyyy 



where "xxxxxxxx" and "}07yj7yy" represent real values. 



FMT_ERRCOUNT; 

.ASCIC 7! /I /BYTES TRANSFERRED: !SL! BAD;!SL!/!/7 



$DS_PRINTB_S FMT_ERRCOUNT, 4(AP), ERR_CNT 
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BLISS-32 
EXAMPLE 



BIND 



FMT ERRCOONT = 

UPLIT (%ASCIC ' !/!/BYTES TRANSFERRED: !SL!_BaD:!5L! /!/') J 



$DS_PRINTB (FMT_ERRCOUNT, .TOTAL, .ERR_CNT); 
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$DS_PRINTF 



The Format and Print ASCII Message system services provide a means by 
which complex messages can be formatted into ASCII character strings 
and displayed on the user terminal. The macros that call these services 
are commonly referred to as the "print" macros. These macros can be 
used to 

• Insert variable character string data into an output string 

• Convert binary values into the ASCII representations of their decimal, 
hexadecimal, or octal equivalents and substitute the results in an 
output string 

The system services construct an output string by referring to formatted 
ASCII output (FAG) directives contained in a "control string" and using 
those directives to operate on the contents of value parameters. 

Once the system service creates the output string, it is automatically 
displayed on the user terminal. 

The $DS_PRINTF macro ("print forced message") is used to display 
informational messages that are not related to device errors. These 
messages are referred to as "forced" messages because they are printed 
regardless of the state of the flags which inhibit message displays (see the 
VAX/DS Diagnostic Supervisor User's Guide). 



MACRO-32 



BLISS-32 



$DS_PRINTF_x format, [pQ], [pi], [p2], [p3], [p4J. [p5J, 

[P6L [p7h [p8], [p9], [pa], [pb], [pc], 
[pd], [pe], [pf] 



$DS_PRINTF (format, [pO], [pi], [p2], [p3], [p4], [p5], 
[p6], [p7], [p8], [p9], [pa], [pb], [pc], [pd], 
[pe], [pf]): 



ARGUMENTS 



format 

Address of a counted ASCII string. This is the "control string," which 
consists of the fixed text of the output string plus FAO directives for 
formatting variable data. FAO directives are listed in Table 5-7. Variable 
data is passed in parameters pO through pf. 

pO through pf 

to 16 directive parameters, contained in longwords. Depending on the 
corresponding FAO directive, a parameter may be a value that is to be 
converted, the address of a string that is to be inserted, a length, or an 
argument count. Parameters are listed in the order they are referenced by 
the control string. 
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RETURN 
STATUS 



SS$_NORMAL 
SS$_BUFFEROVF 

SS$_BADPARAM 



Service successfully completed. 

Service successfully completed, but the size of the 
output string was greater than the maximum allowed 
and was truncated (see notes). 

An invalid FAO directive was specified in the control 
string. 



NOTES 



1 VDS stores the output string in an internal buffer as it is being created. 
This buffer can contain up to 512 characters. If the output string is 
greater than 512 characters, the string is truncated and the truncated 
message is displayed. 

2 If it is necessary to format a message containing more than 16 
pareimeters, it is possible to 

• Use several PRINT macros in succession, or 

• Use the $FAO or $FAOL macros to format the message. The 
message should then be printed using the proper print macro (for 
example, PRINTX for a level 3 error message). 

3 In MACRO-32, the $FAO_S macro form uses a PUSHL instruction 
for all parameters (pi through pn) specified with the macro call. In 
other words, all arguments are assumed to be values, not addresses. 
Therefore, if an address is desired, precede the argument with a # 
character, or load the address into a register. 

4 In a multiprocessing envirorxment, $DS_PRINTxxx cannot be called 
from within a block of code delineated by the $DS_BGNATTACHED 
and $DS_END ATTACHED macros. 

5 FAO Directives. See Note 5 of the $DS PRINTB macro. 



MACRO-32 

EXAMPLE The following examples will display this message: 

This machine is not supported by this diagnostic. 



N0N_SUPP0RTED_CPU : 

.ASCIC "1/ This machine is not supported by this diagnostic.!/" 



$DS_PRINTP_S e*NON_SOPPORTED_CPU 
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BLISS-32 
EXAMPLE 



BIND 



NON_SUPPORTED_CPU = 

UPLIT (%ASCIC '!/!/This machine is not supported by this diagnostic!/'), 



$DS_PRINTF (NON_SUPPORTED_CPU); 
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The Print Revision Level service may be used in diagnostic programs tliat 
test devices for whicii a iiardware, firmware, and/or patch revision level is 
accessible to the program. Such programs may want to indicate whether 
the device's revision levels are compatible with the revision levels expected 
by the program. 

This service will: 

• Compare actual and expected device revision levels specified by the 
diagnostic program 

• Display a message indicating the device's revision level (hardware 
firmware, or patch), and also indicating whether the revision levels 
being compared are hardware levels, firmware levels, or patch levels. 
A module number may be printed, and hardware revision numbers may 
be converted to a letter code. 



• 



Cause the hardware revision level, firmware revision level and/or patch 
level to be included in all error messages (generated via $DS_ERRxxxx 
macros) that are subsequently displayed for the unit in question. 

If the device being tested has a software-readable hardware, firmware, 
or patch level, the $DS_PRINTREV service should be called for each 
selected device. These calls should be made in the "pass 0" section of 
the initialization code. 

If the device has all three (hardware, firmware, and patch) revision types, 
then the service should be called three times for each selected device; 
once to report the hardware revision, once for the firmware revision, and 
once for the patch level. 

For each logical unit, $DS_PRINTREV can be called four times for each 
type of revision level. This allows you to check and report revision levels for 
each module (up to four) of a device with multiple modules (boards). For 
example, it would be desirable to call $DS_PRINTREV twice for hardware 
revision levels if a logical unit was a 2-board device, and each board had 
an associated hardware revision level. (You can use the "modulenum" 
parameter to differentiate the modules.) 

When called, the service will immediately display (at the programmer's 
option) a message indicating the actual revision level and/or messages 
indicating whether the actual revision level matches the revision level 
expected by the diagnostic program. One of the following messages may 
be printed. (DEVNAME will be replaced by the generic name of the unit in 
question, and MODNAME will be replace by the ASCII string specified by 
the "modulenum" parameter, described later.) 



****** 



Hardware revision level of DEVNAME MODNAME: 

Hardware revision level of DEVNAME MODNAME is less than that 
expected by diagnostic program. 

Hardware revision level: 



****** 
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Revision levei expected by program: 

Hardware revision ievei of DEVNAIViE IVIODNAIVIE is equal to tliat expected 
by diagnostic program. 

Hardware revision level: ****** 
Revision level expected by program: 



****** 



Hardware revision ievei of DEVNAME MODNAiVIE is greater than that 
expected by diagnostic program. 



Hardware revision level 

Revision level expected by program: 



****** 

****** 



If firmware or patch levels are being reported, the word "hardware" in the 
messages will be replaced with the word "firmware" or "patch". 

Each time an error service is called ($DS_ERRxxxx) for a unit for which 
the $DS_PRiNTREV macro has been called, the hardware revision level, 
firmware revision level, and/or patch level will be displayed as part of the 
error message. The message will be displayed AFTER all of the error text 
has been printed. It will be inhibited if the IE1 flag is set. The format of 
this display will be: 

****** program title program rev. ****** 

Pass #, test #, subtest #, error #, date 
Hard error while testing DEVNAME: text 

text 

Revision level(s) for DEVNAME: 

MODNAME; Hardware = X; Firmware = X; Patch = X; 
MODNAME: Hardware = Y; Firmware = Y; Patch = Y; 

****** End of hard error number # ****** 

(If any of the levels or the module number are not being reported, they will 
not appear in the revision level message.) 



MACRO-32 $DS_PRINTREV_x logjjnit, actualjev, expected jrev, 

revjype, 
[printmask], [priink], [modulenum] 



BLISS-32 $DS PRINTREV (LOG_UNlT=log_unit, 

ACTUAL_UNIT= actual_rev, 
EXPECTED_REV=expected_rev, 
REVJYPE = revjype, 
[PRINTMASK = printmask], 
[PRLINK= priink], 
[MODULENUM = modulenum]); 
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ARGUMENTS logjinit 

Logical unit number of device whose revision level is to be checked. This 
number should be between and 127. 

actual_rev 

Longword containing the actual hardware, firmware, or patch revision level 
for the device whose logical unit number is specified with the "logunit" 
parameter. See Note 3. (The diagnostic program determines this value by 
accessing the hardware.) 

expectedjev 

Longword containing the hardware, firmware, or patch revision level which 
was expected by the diagnostic program. See Note 3. (This value is placed 
in the diagnostic program at compilation time.) 

revjype 

Longword mask indicating the t5rpe of revision code (hardware, firmware, 
or patch) being compared. Bit definitions are: 

• Bit - PRV$V_HWREV, PRV$M_HWREV - Set this bit to indicate a 
hardware revision level. 

• Bit 1 — PRV$V_FWRE:V, PRV$M_FWREV - Set this bit to indicate a 
firmware revision level. 

• Bit 2 - PRV$V_PREV, PRV$M_PREV - Set this bit to indicate a patch 
level. 

(Only one bit should be set per service call.) 

printmask 

Longword mask used to control $DS_PRINTREV functions. Bit definitions 
are: 

• Bit — PRMSK$V_LSS, PRMSK$M_LSS — If set, inhibits message 
that would normally be displayed if the actual revision is less than 
expected. 

• Bit 1 - PRMSK$V_EQL, PRMSK$M_EQL - If set, inhibits message 
that would normally be displayed if the actual revision is equal to that 
expected. 

• Bit 2 - PRMSK$V_GTR, PRMSK$M_GTR - If set, inhibits message 
that would normally be displayed if the actual revision is greater than 
expected. 

• Bit 3 ~ PRMSK$V_ALWAYS, PRMSK$M_ ALWAYS - If set, displays 
the message which lists only the actual reAdsion level. 

• Bit 4 - PRMSK$V_TRANSL, PRMSK$M_TRANSL - If set, will convert 
a hardware revision number to a letter code which represents the 
functional revision as defined by DEC STD 012. Setting this bit will not 
result in conversion for firmware or patch revisions, llie conversion 
pattern is shown in Table 5-9. 
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Table 5-9 Revision Number to Letter Conversion 

Field contents [bits <n:0>] Functional Rev. 

0000 pre-release 

0001 A 

0010 B 

0011 C 



0.... 11010 
0....11011 
0.... 11100 
0.... 11101 



z 

AA 
AB 
AC 



0... 110100 
0... 110101 



AZ 
BA 



0.. 1001110 



BZ 



1010111110 



zz 



By default, bits through 4 are clear. A message will be displayed stating 
whether the actual revision is greater than, less than, or equal to the 
revision expected by the program. No conversion will be performed on 
revision numbers, inhibiting messages does not affect the inclusion of the 
hardware, firmware or patch revision levels in error messages generated by 
$DS_ERRxxxx macros.) 

priink 

Address of a message routine. This optional routine will have the same 
format as an error reporting routine used with a $DS_ERRxxxx macro. 
That is, the routine should be delineated with $DS_BGNMESSAGE 
and $DS_ENDMESSAGE macros and should use $DS_PRINTB and 
$DS_PRINTX macros for displaying text. The message will be printed 
when the $DS_PRINTREV service is called. 

modulenum 

Address of a counted ASCII string which represents the unique module 
identifer for a device module (board). 
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Note: If you associate a module identifier with a device, you MUST supply the 
"modulenum" argument with each $DS_PRINTREV call for that device, 
whether you are specifying the hardware revision, software revision, or 
patch level. (See the example.) 



RETURN 
STATUS 



DS$_NORMAL 
DS$_OVERFLOW 

DS$JLLUNIT 
DS$_BADTYPE 
DS$_ERROR 
DS$_MEMALLOCERR 



Service successfully completed. 

Exceeding maximum number of devices or modules 

in data structure. 

Logical unit does not exist in p-table. 

Revision type is invalid. 

Hardware revision is out of bounds. 

Not enough memory available tiirough 
EXE$ALONONPAGED. 



NOTES 



1 Symbols are defined by the $DS_PRINTREV_DEF macro. 

2 This macro should only be used for devices having software-accessible 
hardware, firmware, or patch revision numbers. 

3 The format of the revision level is irrelevant, but the values passed via 
the "actual_rev" and "expected_rev" parameters must be in the same 
format. The service will perform an unsigned comparison of the two 
values to determine which message to display. Revision numbers will 
be displayed as unsigned decimal values unless conversion to a letter 
code is desired. 

Recommended Usage: 

This macro is probably best used for determining if the current version 
of a diagnostic program is incompatible with older hardware. Since new 
revisions of the diagnostic program may only run on hardware above 
a certain revision level, the diagnostic should only set bits 1 and 2 in 
printmask. This causes a message to be displayed only if the actual 
revision level is less than that expected by the program. If you do not set 
bit 2 in printmask, a misleading message may result if the actual hardware, 
firmware, or patch levels were updated without a corresponding change to 
the diagnostic's expected revision levels. 

Normally, the hardware revision level should be converted to the 
corresponding functional revision letter code by setting bit 4 in 
"printmask". 
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MACRO-32 
EXAMPLE 



TlOOl: 



.ASCIC "TlOOl" 

$DS_PRINTREV_S - 

Log_Unit = Unit_Num,- 
Actual_Rev = CPU_Rev,- 
Expected_rev = #1,- 



Rev_Type = #prv$m_hwrev, 
Printmask = #'>X1E,- 

Modulenum = TlOOl 

$DS_PRINTREV_S - 

Log_Unit = Unit_Num,- 
Actual_Rev = uCode_Rev,- 
Expected_rev = #20,- 

Rev_Type = #prv$m_fwrev, 

Printmask = #'^XE,- 

Modulenum = TlOOl 



[Device's logical unit number 

f Actual rev, as read from HW 

[Lowest hardware rev that 

f will work with this diagnostic. 

; (Converted to "A" before 

r printing. ) 

-; Indicate that this is a 

; hardware parameter. 

; Inhibit equal or greater than 

; message, enable informational 

; message, convert to letter. 

; Address of ascic message 

; "TlOOl". 

(•Device's logical unit number 

; Actual rev, as read fro!n,,IJW 

; Lowest ucode rev that will 

; work with this diagnostic. 

-; Indicate that this is a 

; firmware rev parameter. 

; Inhibit equal or greater than 

; message, enable informational 

; message. 

;Address of ascic message 

; "TlOOl". 



$DS_PRINTREV_S - 

Log_Unit = Unit_Num,- ; Device's logical unit number 
Actual_Rev = Patch_Rev,-; Actual rev, as read from HW 
Expected_Rev = #1,- ; Lowest ucode patch rev that 

;will work with this diagnostic. 
Rev_Type = tprv$m_prev,-; Indicate that this is a 
- ; patch level parameter. 
Printmask = #'XE,- ; Inhibit equal or greater than 

; message, enable informational 

; message. 
Modulenum = TlOOl /Address of ascic message 

; "TlOOl". 
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The Format and Print ASCII Message system sen/ices provide a means by 
whicli complex messages can be formatted into ASCii character strings 
and displayed on the user terminal. The macros that call these services 
are commonly referred to as the "print" macros. These macros can be 
used to 

• Insert variable character string data into an output string 

• Convert binary values into the ASCII representations of their decimal, 
hexadecimal, or octal equivalents and substitute the results in an 
output string 

The system services construct an output string by referring to formatted 
ASCII output (FAG) directives contained in a "control string" and using 
those directives to operate on the contents of value parameters. 

Once the system service creates the output string, it is automatically 
displayed on the user terminal. 

The $DS_PRINTS macro ("print summary message") is used exclusively to 
display program summary messages (see Section 3.7, Summary Routine). 
Display of messages generated with this macro will be inhibited if the VDS 
control flag lES is set (see the VAX/DS Diagnostic Supervisor User's Guide). 



IVIACRO-32 



$DS„PRINTS_x 



format, [pO], [pi], [p2}, [p3]. [p4], [pS], 
[p6L [P7L [p8], [p9], [pa], [pb], [pc], 
[pd], [pe], [pf] 



BLISS-32 



$DS_PRINTS (format, [pO], [p1], [p2], [p3], [p4], [p5], 
[p6], [p7], [pd], [p9], [pa], [pb], [pc], 
[pd], [pe], [pf]); 



ARGUMENTS 



format 

Address of a counted ASCII string. This is the "control string," which 
consists of the fixed text of the output string plus FAO directives for 
formatting variable data. FAO directives are listed in Table 5-7. Variable 
data is passed in parameters pO through pf . 

pO through pf 

to 16 directive parameters, contained in longwords. Depending on the 
corresponding FAO directive, a pariuneter may be a value that is to be 
converted, the address of a string that is to be inserted, a length, or an 
argument count. Parameters are listed in the order they are referenced by 
the control string. 
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RETURN 
STATUS 



SS$_NORMAL 
SS$_BUFFEROVF 

SS$_BADPARAM 



Service successfully completed. 

Service successfully completed, but the size of tfie 
output string was greater than the maximum allowed 
and was truncated (see notes). 

An invalid FAO directive was specified in the control 
string. 



NOTES 



1 VDS stores the output string in an internal buffer as it is being created. 
This buffer can contain up to 512 characters. If the output string is 
greater than 512 characters, the string is truncated and the truncated 
message is displayed. 

2 If it is necessary to format a message containing more than 16 
parameters, it is possible to 

• Use several PRINT macros in succession, or 

• Use the $FAO or $FAOL macros to format the message. The 
message should then be printed using the proper print macro (for 
example, PRINTX for a level 3 error message). 

3 In MACRO-32, the $FAO_S macro form uses a PUSHL instruction 
for all parameters (pi through pn) specified with the macro call. In 
other words, all arguments are assumed to be values, not addresses. 
Therefore, if an address is desired, precede the argument with a # 
character, or load the address into a register. 

4 In a multiprocessing envirorunent, $DS_PRINTxxx cannot be called 
from within a block of code delineated by the $DS_BGNATTACHED 
and $DS_END ATTACHED macros. 

5 FAO Directives. See Note 5 of the $DS_PRINTB macro. 



IVIACRO-32 

cXAMPLE The following examples will display this message: 

MEMORY ERROR SUMMARY AS OF l-FEB-1989 16:26!ll. 



FMT_SUM_HEAD : 

.ASCIC "! /Memory Error Summary as of !%T.!/" 



$DS PRINTS S g#FMT SUM HEAD 
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BLISS-32 
EXAMPLE 



BIND 



FMT_SUM_HEAD = 

ASCIC ('!/!/Memory Error Sunmary as of i%T.!/')/ 



$DS_PRINTS ( FMT_SUM_HEAD ) ; 
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The Print Signal Array system service will format and print the contents 
of a signal array. Signal arrays are passed to condition handlers when 
exception conditions occur. Refer to Section 4.4.5, Condition Handling. 



MACRO-32 



$DS_PRINTSIG_G argptr 

(Only the _G form of the macro is supported.) 



BLISS-32 



$DS_PRINTSIG (ARGPTR = argptr); 



ARGUMENTS 



argptr 

Address of the signal array. 



RETURN 
STATUS 



SS$_NORMAL 
SS$_RESIGNAL 



Service successfully completed. 

The VDS does not support condition handling for 
the detected condition. The signal array will not be 
displayed. The following conditions will always result 
in this return status: SS$_PAGRDERR, SS$_FAIL, 
SS$_DEBUG. and SS$_ARTRES. 



IVIACRO-32 
EXAMPLE 



$DS_PRINTSIG_G @4(AP) 



These examples illustrate use of the macro within a condition handler. 
Condition handlers receive the signal array address as the first argument 
on the argument stack. 



;Display signal array 



BLISS-32 
EXAMPLE 

$DS_PRINTSIG (ARGPTR = . ( .AP + 4)); 'Display signal array 
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The Format and Print ASCII Message system services provide a means by 
which complex messages can be formatted into ASCII character strings 
and displayed on the user terminal. The macros that call these services 
are commonly referred to as the "print" macros. These macros can be 
used to 

• Insert variable character string data into an output string 

• Convert binary values into the ASCII representations of their decimal, 
hexadecimal, or octal equivalents and substitute the results in an 
output string 

The system services construct an output string by referring to formatted 
ASCII output (FAG) directives contained In a "control string" and using 
those directives to operate on the contents of value parameters. 

Once the system service creates the output string, it is automatically 
displayed on the user terminal. 

The $DS_PRINTX macro ("print extended error message") is used 
exclusively to display the third message level of error messages (see 
Section 3.9, Reporting Errors). Display of messages generated with this 
macro will be inhibited if the VDS control flag IE3 is set (see the VAX/DS 
Diagnostic Supervisor User's Guide). 



IVIACRO-32 



$DS_PRINTX_x format, [pO], [p1], [p2J, [p3J. [p4], [p5]. 

[p6h IP71 [pdj, [p9], [pa], [pb], [pel 
[pd], [pel [pf] 



BLISS'-32 



$DS_PRINTX (format, [pO], [p1], [p2J, [p3], [p4], [p5], 
[p6L [p7], [p8], [p9], [pa], [pb], [pc], [pd], 
[pe], [pf]); 



ARGUMENTS 



format 

Address of a counted ASCII string. This is the "control string," which 
consists of the fixed text of the output string plus FAO directives for 
formatting variable data. FAO directives are listed in Table 5-7. Variable 
data is passed in parameters pO through pf . 

pO through pf 

to 16 directive parameters, contained in longwords. Depending on the 
corresponding FAO directive, a parameter may be a value that is to be 
converted, the address of a string that is to be inserted, a length, or an 
etrgument count. Parameters are listed in the order they are referenced by 
the control string. 
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RETURN 
STATUS 



SS$_NORMAL 
SS$_BUFFEROVF 

SS$_BADPARAM 



Service successfully completed. 

Service successfully completed, but the size of tfie 
output string was greater thian the maximum allowed 
and was truncated (see notes). 

An Invalid FAO directive was specified In the control 
string. 



NOTES 



1 VDS stores the output string in an internal buffer as it is being created. 
This buffer can contain up to 512 characters. If the output string is 
greater than 512 characters, the string is truncated and the truncated 
message is displayed. 

2 If it is necessary to format a message containing more than 16 
parameters, it is possible to 

• Use several PRINT macros in succession, or 

• Use the $FAO or $FAOL macros.to format the message. The 
message should then be printed using the proper print macro (for 
example, PRINTX for a level 3 error message). 

3 In MACRO-32, the $FAO_S macro form uses a PUSHL instruction 
for all parameters (pi through pn) specified with the macro call. In 
other words, all arguments are assumed to be values, not addresses. 
Therefore, if an address is desired, precede the argument with a # 
character, or load the address into a register. 

4 In a multiprocessing environment, $DS_PRINTxxx cannot be called 
from within a block of code delineated by the $DS_BGNATTACHED 
and $DS_ENDATTACHED macros. 

5 FAO Directives. See Note 5 of the $DS_PRINTB macro. 



MACRO-32 
EXAMPLE 



The following examples will display this message: 



PC at Failure: 453AE(X) 
ERROR Address: 11B6(X) 
SCB Vector: 10 (X) 
Error Code: 5900(D) 



Error_Msg_Level3 : 

.ASCIC \!/PC at Failure: 1_!AC(X)\- 
\!/Error Address: !~!AC(X) \- 
\!/SCB Vector: !_!AC(X) \- 
\!/Error Code: !_!AC(D)\ 

$DS_PRINTX_S Er rorMsg_level3 , Rl 1 , RIO , R8 , R7 
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BLISS-32 
EXAMPLE 

LOCAL 

FAIL_PC, 
ERR_ADR, 
SCB_VEC, 
ERR~CODE; 

BIND 

ErrorMsg_Level3 = 

UPLIT (%ASCIC \!/!\PC at Failure: !_!AC (X)\- 
\!/ Error Address: !_! AC (X)\- 
\!/ see Vector: !_! AC (X)\- 
\!/ Error Code:!-!AC (D)\) 

$DS_PRINTX (ErrorMsg_Level3, .FAIL_PC, .ERR_ADR, .SCB_VBC, .ERR_CODE); 
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The Probe Device Address system service of tiie VDS may be used to 
determine if a device resides at a particular physical address. The service 
is passed the address to be checked and the logical unit number of the 
device that is expected to be at that address, and it will return a status 
code indicating whether or not the address exists. 

This service is only available to level 3 programs. 



MACRO-32 $DS_PROBE_x address, length, unit 



BLISS-32 



$DS_PROBE (ADDRESS = address, LENGTH = length, 
UNIT = unit); 



ARGUMENTS 



address 

The physical address whose existence is to be determined. 

length 

Size of the location specified by "address." Valid values are 1 for b3rte, 2 
for word, and 4 for longword. 

unit 

Logical unit number of the device expected to be at the specified address. 



RETURN 
STATUS 



SS$_NORMAL Service successfully completed. 

DS$_ERROR An invalid value was specified for "length" or "unit". 

DS$_MCHK The specified address does not exist, or the device 

existing at address does not respond. 

DS$_LOGIC The device is not functioning correctly. 

SS$_ACCVIO, DS$_TRANSL Page tables do not allow access. 
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IVIACRO-32 
EXAMPLE 



This example probes devices on a MASSBUS controller. 



$DS_GPHARD_S - 

LOG UNIT, PTABLE 



; Get p-table. 



MOVL PTABLE, R3 

MOVL B^HP$A_DEVICE ( R3 ) , RIO 

CLRL Rll 

$DS_PROBE_S - 

ADDRESS = (RIO) [Rll] 
LENGTH = #4 
UNIT = LOG_UNIT 

$DS BERROR ERRIO 



Get p-table address . 

Get MBA controller register 

base address. 

Init. controller register pointer 

See if the drive unit exists. 



(Continue) 



ERRIO ! (Report error - device not there.) 



BLISS-32 
EXAMPLE 



$DS_GPHARD (UNIT=.LOG_UNIT, RETADR=PTABLE ) ; 
CONTROLLER_BASE = .PTABLE [HPSA_DEVICE] ; 
DEVICE_ADDR = . CONTROLLER_BASE ; 
WHILE TdEVICE_ADDR LSS LAST_DEVICE DO 

BEGIN 

IF NOT $DS_PR0BE (ADDRESS=.DEVICE_ADDR, 

LENGTH=4, UNIT=.L0G_UNIT) 

THEN BEGIN ...Report error - drive not there.. 

ELSE DEVICE_ADDR = .DEVICE_ADDR + NEXT_DEVICE 

END; 



END 
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The $DS_PSLDEF macro defines (for MACRO-32 programs) symbolic 
names for fields of the process status longword. For BLISS-32 programs, 
these symbols may be referenced without first issuing the $DS_PSLDEF 
macro. 

Symbols defined are: 

PSLSV_CBIT PSL$M_CBIT 

PSL$V_VBIT PSL$M_VBIT 

PSL$V~ZBIT PSL$M_ZBIT 

PSL$V~NBIT PSLSM~NBIT 

PSL$K_KERNAL 
PSL$K_EXEC 
PSL$K_SUPER 
PSI.$K USER 



IVIACRO-32 $DS_PSLDEF [gbl] 



ARGUMENTS gbl 



MACRO-32 
EXAMPLE 

$DS PSLDEF GLOBAL 
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The $DS_PTDDEF macro defines (for MACRO-32 programs) symbolic 
names for the flags associated with the $DS_$NAME p-table descriptor 
macro. For BLISS-32 programs, these symbols may be referenced without 
first issuing the $DS_PTDDEF macro. 

Symbols defined are: 

PTD$M_UN1T PTDSV_UNIT 

PTD$M_CONTROLLER PTD$V_CONTR0LLER 
PTD$M_NAME PTD$V_NAME 

PTD$M_INHERIT_PRE PTD$V_INHERIT_PRE 
PTD$M_INHERIT~CON PTD$V_INHERIT_CON 
PTD$M_INHERIT~ 
PTD$M_DEVICE 
PTD$V ENDDEVICE 



MACRO-32 $DS_PTDDEF 



MACRO-32 
EXAMPLE 

$DS PTDDEF 
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$QIO~$QIOW 



The Queue I/O Request system service ($QIO) initiates an I/O operation 
in user mode by queueing a request to an I/O cliannel. The channel 
must have been previously assigned with $ASSIGN service. Once the I/O 
request has been queued, control returns to the caller. Notification that 
the I/O operation has completed can be accomplished by one of three 
methods: 

• An AST routine can be caused to execute when I/O has completed. 

• The diagnostic program can specify that an event flag be set when I/O 
has completed. 

• The diagnostic program can specify that an I/O status block be filled in 
when I/O has completed. 

These methods for notification of I/O completion are discussed in 
Section 4.2.1.1, I/O in User Mode. 

The Queue I/O Request and Wait for Event Flag system service (SQIOVV) 
combines the operations of the $QIO and $WAITFR (Wait for Single Event 
Flag) system services. 

The $QIO and $QIOW services may not be used by level 3 programs. 



MACRO-32 



$QIO_x efn, chan, func, [iosb], [astadr], [astprm], [pi], 
[p2], [p3], [p4], [p5], [p6] 



BLISS-32 



$QIO (EFN = efn, CHAN = chan. FUNC = func, 
[IOSB = iosb], [ASTADR = astadr], 
[ASTPRM = astprm], [P1 =p1], [P2=p2], 
[P3 = p3], [P4 = p4], [P5 = p5], [P6 = p6]); 



ARGUMENTS efn 

Number of the event flag that is to be set at request completion. 

Note: If an event flag is not specified, the default is 0. Since event flag is 
used by the VDS, a nonzero value for this parameter must ALWAYS be 
specified, for both the $QIO and the $QIOW macros, whether or not the 
diagnostic program actually tests this flag as a means of determining that 
the I/O operation has completed. 

Chan 

Number of the I/O channel assigned to the device to which the request is 
directed. Obtained by using the $ASSIGN macro. 
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func 

Function code and modifier bits that specify the operation to be performed. 
An introduction to function codes is provided in Section 4.2.1.1, I/O in 
User Mode. Complete documentation of function codes is located in the 
VAX/VMS I/O User's Guide. 

iosb 

Address of a quadword I/O status block that is to receive final completion 
status. See "Synchronizing I/O Completion" in Section 4.2.1.1, I/O in User 
Mode. 

astadr 

Address of the entry mask of an AST routine to be executed when the I/O 
completes. The AST routine will execute at the access mode from which 
the $QIO macro was issued. See "Synchronizing I/O Completion" in 
Section 4.2.1.1, I/O in User Mode. 

astprm 

AST parameter to be passed to the AST routine. See Section 4.4.3. 

p1top6 

Optional device- and function-specific parameters. Refer to the VAXA^MS 
I/O User's Guide. 

The first parameter may be specified as "pi" or as "plv," depending on 
whether an address or a value is required, respectively. If the ke37word 
is not used, "pi" is the default and the argument is considered to be an 
ADDRESS. 

P2 through P6 are always interpreted as VALUES. 



RETURN 
STATUS 



SS$_NORMAL 

SS$_ABORT 
SS$_ACCVIO 



SS$_DEVOFFLINE 
SS$_EXQUOTA 



SS$JLLEFC 
SS$_INSFMEM 



Service successfully completed. The I/O request 
packet was successfully queued. 

A network logical link was broken. 

The I/O status block cannot be written by the caller. 

This status code may also be returned if parameters 
for device-dependent function codes are Incorrectly 
specified. 

The specified device is offline. 

The process has exceeded its buffered I/O quota, 
direct I/O quota, or buffered I/O byte count quota 
and has disabled resource wait mode with the Set 
Resource Wait Mode ($SETRWIW) system service; or 
the process has exceeded Its AST limit quota. 

An Illegal event flag number was specified. 

Insufficient system dynamic memory Is available to 
complete the service, and the process has disabled 
resource wait mode with the Set Resource Wait 
Mode ($SETRWM) system service. 
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SS$JVCHAN 

SS$_NOPRIV 
SS$_UNASEFC 



An invalid channel number was specified; tiiat is, a 
channel number of or a number larger than the 
number of channels available. 

The specified channel does not exist or was 
assigned to a more privileged access mode. 

The process Is not associated with the cluster 
containing the specified event flag. 



NOTES 



1 See the VAX/VMS System Services Reference Manual for discussions of 
privilege restrictions, resource requirements, and other notes relating to 
the $QIO and $QIOW macros. 



MACRO-32 
EXAMPLE 



$QIO_S EFN=#1, - 

chan=ttchan1, - 
func=# i os_wri teblk , 
pi=bufadd7- 
p2=#bufsize 



; Event flag 1 

; Channel 

;Virtual write function 

; Buffer address 

;Buffer size 



BLISS-32 
EXAMPLE 



IF NOT {STATUS=$QIOW (EFN=32, CHAN=.LOG_UNIT, 
FUNC=IO$_SETM0DE OR IO$M_ATTAST, 
lOSB = SETMODE_IOSB, P1=ATNAST) 

THEN 

BEGIN 

(Report error.) 
END; 
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$QIOW— $QIO 



The Queue I/O Request system service ($QIO) initiates an i/0 operation 
in user mode by queueing a request to an I/O channel. The channel 
must have been previously assigned with $ASSiGN service. Once the I/O 
request has been queued, control returns to the caller. Notification that 
the I/O operation has completed can be accomplished by one of three 
methods; 

• An AST routine can be caused to execute when I/O has completed. 

• The diagnostic program can specify that an event flag be set when I/O 
has completed. 

• The diagnostic program can specify that an I/O status block be filled in 
when I/O has completed. 

These methods for notification of I/O completion are discussed In 
Section 4.2.1.1, I/O in User IVIode. 

The Queue I/O Request and Wait for Event Flag system service ($QIOW) 
combines the operations of the $QIO and SWAITFR (Wait for Single Event 
Flag) system services. 

The $Q!0 and $QIOW services may not be used by level 3 programs. 



MACRO-32 



$QIOW_x efn, chan, func, [iosb], [astadr], [astprm], 
[p1L [p2h [p3h [p4], [p5h [p6] 



BLISS-32 



$QIOW (EFN = efn, CHAN = chan, FUNC = func, 
[IOSB = iosbj, [ASTADR = astadr], 
[ASTPRM = astprm], [P1 =p1], [P2 = p2], 
[P3 = p3], [P4 = p4], [P5 = p5], [P6 = p6]): 



ARGUMENTS efn 



Number of the event flag that is to be set at request completion. 

Note: If an event flag is not specified, the default is 0. Since event flag is 
used by the VDS, a nonzero value for this parameter must ALWAYS be 
specified, for both the $QIO and the $QIOW macros, whether or not the 
diagnostic program actually tests this flag as a means of determining that 
the I/O operation has completed. 

Chan 

Number of the I/O channel assigned to the device to which the request is 
directed. Obtained by using the $ASSIGN macro. 
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tunc 

Function code and modifier bits that specify the operation to be performed. 
An introduction to function codes is provided in Section 4.2.1.1, I/O in 
User Mode. Complete documentation of function codes is located in the 
VAX/VMS I/O User's Guide. 

losb 

Address of a quadword I/O status block that is to receive final completion 
status. See "Synchronizing I/O Completion" in Section 4.2.1.1, I/O in User 
Mode. 

astadr 

Address of the entry mask of an AST routine to be executed when the I/O 
completes. The AST routine will execute at the access mode from which 
the $QIO macro was issued. See "S3mchronizing I/O Completion" in 
Section 4.2.1.1, I/O in User Mode. 

astprm 

AST parameter to be passed to the AST routine. See Section 4.4.3. 

pi top6 

Optional device- and function-specific parameters. Refer to the VAX/VMS 
I/O User's Guide. 

The first parameter may be specified as "pi" or as "plv," depending on 
whether an address or a value is required, respectively. If the keyword 
is not used, "pi" is the default and the argument is considered to be an 
ADDRESS. 

P2 through P6 are always interpreted as VALUES. 



RETURN 
STATUS 



SS$_NORMAL 

SS$_ABORT 
SS$_ACCVIO 



SS$_DEVOFFLINE 
SS$_EXQUOTA 



SS$JLLEFC 
SS$JNSFMEM 



Service successfully completed. The I/O request 
packet was successfully queued. 

A network logical link was broken. 

The I/O status block cannot be written by the caller. 

This status code may also be returned If parameters 
for device-dependent function codes are incorrectly 
specified. 

The specified device is offline. 

The process has exceeded its buffered I/O quota, 
direct I/O quota, or buffered I/O byte count quota 
and has disabled resource wait mode with the Set 
Resource Wait Mode ($SETRWM) system service; or 
the process has exceeded its AST limit quota. 

An illegal event flag number was specified. 

Insufficient system dynamic memory is available to 
complete the service, and the process has disabled 
resource wait mode with the Set Resource Wait 
Mode ($SETRWM) system service. 
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SS$_IVCHAN 

SS$_NOPRIV 
SS$_UNASEFC 



An invalid channei number was specified; that is, a 
channel number of or a number larger than the 
number of channels available. 

The specified channel does not exist or was 
assigned to a more privileged access mode. 

The process is not associated with the cluster 
containing the specified event flag. 



NOTES 



1 See the VAX/VMS System Seivices Reference Manual for discussions of 
privilege restrictions, resource requirements, and other notes relating to 
the $QIO and $QIOW macros. 

2 Two potential problems exist when the $QIOW service is used: 

• If the I/O device is malfunctioning, the event flag may never be set 
and service will never return to the diagnostic program. 

• If the I/O device is slow or overloaded, the restriction that control- 
Cs be checked at least every three seconds may be violated (see 
Section 4.4.6, Handling Control-Cs). 

It is therefore better for diagnostic programs to use the $QIO and 
$WAITFR services. Additionally, the $SETIMR service should be used 
to limit the amount of time in which the program will wait for the event 
flag, in case it never becomes set. 



MACRO-32 
EXAMPLE 



$QI0_S EFN=#1, - 

CHAN=TTCHAN1, - 
FUNC=#IO$_WRITEBLK, 
P1=BUFADD,- 
P2=#BUFSIZE 



; Event flag 1 

; Channel 

;Virtual write function 

; Buffer address 

fBuffer size 



BLISS-32 
EXAMPLE 



IF NOT (STATUS=$QI0M (EFN=32, CHAN=.L0G_UNIT, 
PUNC=I0$_SETM0DE OR IOSM_ATTAST, 
lOSB = siTMODE_IOSB, P1=ATNAST) 

THEN 

BEGIN 

( Report error . ) 
END; 
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The $RAB macro is used to allocate an RMS record access block (RAB) 
at program compilation time and, optionally, to load values into the various 
fields within the RAB. An RAB Is a data structure that is required for 
performing file management operations using RMS. Refer to Section 4.5, 
File Management. 

This description only discusses RAB fields supported by VDS RMS. For 
a discussion of VMS RMS-supported fields, refer to the VAX/VMS RMS 
Reference Manual. 

Besides allocating the RAB, the $RAB macro also defines symbols for 
each RAB field. Symbols are of the form "RAB$datatype_fieldname," 
where "datatype" is a data type specifier listed in Table 6-1. 



MACRO-32 



$RAB BKT=bkt-coder 

FAB = fab-address,- 

RAC = rac-param,- 

RHB = header-buffer-address,- 

ROP = BIO,- 

UBF = user-buffer-address,- 

USZ = user-buffer-size 



BLISS-32 



$RAB (BKT=bkt-code, 

FAB = fab-address, 

RAC = rac-param, 

RHB - header-buffer-address, 

ROP = BIO, 

UBF = user-buffer-address, 

USZ = user-buffer-size); 



ARGUMENTS 



BKT = bkt'Code 

Bucket code. Used only with block I/O. Should be loaded with the number 
of the first virtual block that is to be read by the $READ service. If is 
specified, reading will begin at block for the first $READ, or at the block 
pointed to by the internal "next block pointer" for subsequent $READs. 

FAB = fab-address 

Address of the FAB describing the file to be accessed. 
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RAC = rac-param 

Record access mode. Indicates the type of access to be used in retrieving 
records from the file. Valid values are 

• SEQ — Sequential record access. This is the default. 

• RFA — Random access by record's file address (RFA). 

Refer to Section 4.5.6, Record Processing, and Note 2 below. 

RHB = header-buffer-address 

Address of buffer to store record header buffer. Used only for files 
consisting of variable records with fixed-length control. The $GET service 
will load the record's header into the specified buffer. The size of this 
buffer must match the size specified by the FSZ field of the FAB. 

ROP = BIO 

Block I/O. Only meaningful if BRO was set in the FOP field of the FAB 
before $OPEN was issued. If so, then setting the BIO record processing 
option will enable record processing and block processing to be mixed. 

UBF = user-buffer-address 

Address of a buffer to receive record fetched by $GET or block fetched by 
$READ. Buffer size is specified with USZ. 

USZ = user-buffer-size 

Size (number of bytes) of buffer pointed to by UBF field. 



NOTES 

1 Read-Only RAB Fields 

The following RAB fields are not loaded by the programmer under 
VDS RMS. They are filled in by RMS services, and may be read after 
the service has completed. (Some of these fields are read/write in VMS 
RMS.) 

BID — Block identifier field. Identifies the block as a RAB. 

BLN — Block length field. Contains the length of the RAB. 

ISI — Internal stream identifier. Associates the RAB with an FAB. 

RBF — Contains the address of the last record read. 

RFA — Record's file address. File address of last record read. See 
Note 2. 

RSZ — Length, in b3^es, of the last record read. 

STS — Completion status code field. RMS services load this field 
with a success or failure completion status before returning to the 
caller of the service. The completion status code is also passed to 
the caller in RO. 

STV — Status value field. Sometimes used to pass additional status 
information from a service to the caller. 
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2 Record's File Address (RFA) 

After a successful $GET operatiort, the file address of the record read 
into memory is stored in the RFA field. The program can extract this 
field and store it elsewhere in memory. Then if it is later necessary to 
re-read the record, the program returns the extracted address to the 
RFA, sets the record access mode to random-by-RFA (by setting RFA 
in RAC), and issues another $GET. 

The RFA field is six bytes long. There are two ways to reference the 
field: 

a. RAB$W_RFA is the field's offset into the RAB. RAB$S_RFA is the 
field's size. Thus the field may be copied as follows: 

MOVAL RABBLK, RO 

M0VC3 #RAB$S_RFA, RAB$W_RFA ( RO ) , SAVE_RFA 

b. RAB$LRFAO is the offset of the first longword of the six-byte field. 
RAB$WRFA4 is the offset of the last word of the field. Thus the 
field may be copied as follows: 

MOVAL RABBLK, RO 

MOVL RAB$L_RFAO(RO), SAVE_RFA 

MOVW RAB$W_RFA4(R0), SAVE_RFA+4 

Table 5-10 lists all of the RAB fields. 



Table 5-10 


RAB Fields 






Field and 

Keyword 

Name 


Field Size 


Description 


Offset 


BID 


Byte 


Block identifier 


RAB$B_BID 


BKT 


Longword 


Budget code 


RAB$L_BKT 


BLN 


Byte 


Blocl< length 


RAB$B_BLN 


CTX 


Longword 


Context 


RAB$L_CTX 


FAB 


Longword 


File access block address 


RAB$L_FAB 


IS! 


Word 


Internal stream identifier 


RAB$W_ISI 


KBF 


Longword 


Key buffer address 


RAB$L_KBF 


KRF 


Byte 


Key of reference 


RAB$B_KRF 


MBC 


Byte 


Multiblock count 


RAB$B_MBG 


MBF 


Byte 


Multibuffer count 


RAB$B_MBF 


PBF 


Longword 


Prompt buffer address 


RAB$L_PBF 


PSZ 


Byte 


Prompt buffer size 


RAB$B_PSZ 


RAC 


Byte 


Record access mode 


RAB$B_RAC 


RBF 


Longword 


Record address 


RAB$L_RBF 


RFA 


3 words 


Record's file address 


RAB$W_RFA 


RHB 


Longword 


Record header buffer 


RAB$L_RHB 


ROP 


Longword 


Record-processing options 


RAB$L_ROP 


RSZ 


Word 


Record size 


RAB$W_RSZ 
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Table 5-10 (Cont.) RAB Fields 



Field and 

Keyword 

Name 


Field Size 


Description 


Offset 


STS 


Longword 


Completion status code 


RAB$L_STS 


STV 


Longword 


Status value 


RAB$L_STV 


STVO 


Word 


Low-order word of status 
value 


RAB$W_STVO 


STV2 


Word 


High-order word of status 
value 


RAB$W_STV2 


TMO 


Byte 


Timeout period 


RAB$B_TMO 


UBF 


Longword 


User record area address 


RAB$L_UBF 


USZ 


Word 


User record area size 


RAB$W_USZ 





MACRO-32 
EXAMPLE 

BUFFER: .BLKB 50 
BUF_SIZE = . - BUFFER 
FAB_BLOCKl 

$FAB FNM=<INFILE.DAT> 
RAB_BLOCK: 

$RAB FAB=FAB_BLOCK, - 
RAC=SEQ, - 
UBF=BUFFER, - 
USZ=BUF SIZE 



BLISS-32 
EXAMPLE 

LITERAL 

BUF SIZE = 50; 



OWN 

BUFFER 
FAB_BLOCK 
RAB BLOCK 



VECTOR [BUF_SIZE, BYTE], 
$FAB ( FNM= ' FILEl . DAT ' ) , 
$RAB ( FAB=FAB_BL0CK, 
RAC=SEQ, 
UBF=BUFFER, 
USZ=BUF_SIZE) ; 
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$RABJNIT 



The $RAB_INIT macro can be used to load RAB fields at run time in 
BLISS-32 programs. Refer to the discussion of the $RAB macro for a 
description of RAB fields. 



BLISS-32 $RABJNIT (RAB = rab-address, 

BKT=bkt-code, 
FAB = fab-address, 
RAC = rac-param, 
RHB = header-buffer-address, 
ROP^BIO, 

UBF = user-buffer-address, 
USZ = user-buffer-size); 

Refer to the discussion of the $RAB macro for descriptions of input 
parameters. With the exception of RAB_address, all parameters are 
optional. 



BLISS-32 
EXAMPLE 



OWN IN_RAB: $E^B(FAB=IN_FAB) ; 
LOCAL 

INBUF ; VECTOR [50, BYTE] ; 

$RRB_INIT (RAB=IN_E?AB, 

UBF=INBUF, UBZ=BUF SIZE) 
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$RAB_STORE 



The $RAB_STORE macro can be used to load RAB fields at run time for 
MACRO-32 programs. Refer to the discussion of the $RAB macro for a 
description of RAB fields. 



MACRO-32 



$RAB_STORE RAB = rab-address,- 

BKT=bkt'C0de,- 
FAB = fab-addressr 
RAC = rac-param,- 
RHB = header-buffer-address,- 
ROP = BIO,- 

UBF = user-buffer-addressr 
USZ = user-buffer-size 



MACRO-32 
EXAMPLE 



BOF_SIZE = 50 
IN_RAB: $RAB 
IN~BUF; .BLKB BUF SIZE 



$RAB_STORE 



RAB=IN_RAB, - 
UBF=IN_BUF, - 
UBZ=»BUF SIZE 
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The Read File service of RIVIS is used to read a specified number of bytes, 
starting at a block boundary, from a file. The file must have been opened 
and connected, using the $OPEN and $CONNECT services, respectively. 



MACRO-32 $READ rab, [err], [sue] 



BLISS-32 



$READ (RAB = rab, [ERR = err], [SUC = sue]); 



ARGUMENTS rab 



RETURN 
STATUS 



Address of the RAB to be associated with the FAB describing the file to 
which connection is to be made. (The address of the FAB is in the RAB.) 

err (user mode only) 

Address of a routine to be executed on error return from the service. 

SUC (user mode only) 

Address of a routine to be executed on successful return from the service. 



RMS$_NORMAL 

RMS$_EOF 

RMSS.FAB 

RMS$_IFI 

RMSSJSI 

RMS$_RAB 

RMS$_RER 



Service successfully completed. 

Attempt was made to read beyond end of file. 

The FAB block is invalid. 

The FAB's IFI field is invalid. 

The RAB's ISI field is invalid. 

The RAB block is Invalid. 

Read error. (The device driver's return status will be 
in the STV field of the RAB.) 



Note: For further details on return status values, refer to the VAX-11 RMS 
Reference Manual. 
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NOTES 



1 Table 5-11 lists the RAB fields used by the $READ service in standalone 
mode. For user mode, refer to the VAX-11 RMS Reference Manual. 

Table 5-11 RAB Fields Used by $READ (Standalone Mode) 



Field Mnemonic 



Field Name 



Input: 

BKT 

ISI 
UBF 

USZ 

Output: 

RBF 

RFA 

RSZ 

STS 
STV 



Bucket number. Must contain the virtual blocl< number of 
the first blocl< to be read. 

Internal stream identifier. 

User record area address. This is where the block will be 
stored. 

User record area size. Indicates length of the transfer, in 
bytes. 

Record address. 

Record's file address. Contains the virtual block number of 
the first block transferred. 

Record size. Indicates the actual number of bytes 
transferred. 

Completion status code. (Also contained in RO.) 

Status value. (See Return Status, above.) 



MACRO-32 
EXAMPLE 

$READ RAB=RAB BLOCK 



BLISS-32 
EXAMPLE 

$READ <RAB=RAB_BL0CK); 
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$READEF 



The $READEF macro is used to obtain the current status of all flags within 
an event flag cluster. Event flags are discussed in Section 4.4.2. 



MACRO-32 
FORMAT: 



$READEF_x efn, state 



BLISS-32 



$READEF (EFN = efn, STATE = state); 



ARGUMENTS efn 



Number of any event flag within the cluster to be read. A flag of number 1 
through 31 specifies cluster 0, and a flag of number 32 through 63 specifies 
cluster 1. 

State 

Address of a longword to receive the status of all event flags within the 
cluster. 



RETURN 
STATUS 



SS$_WASCLR 

SS$_WASSET 

SS$_NORMAL 

SS$_ACCVIO 

SS$_ILLEFC 
SS$_UNASEFC 



Service successfully completed. The specified event 
flag is clear. User mode only. 

Service successfully completed. The specified event 
flag was set. User mode only. 

Sen/Ice successfully completed. Standalone mode 
only. 

The address specified in the "state" parameter 
could not be written by the caller. User mode only. 

An illegal event flag number was specified. 

In user mode, indicates that the specified common 
event flag (see Section 4.4.2) has not been 
associated with the process issuing the $CLREF 
macro. 

In standalone mode, indicates that an event flag 
from 64 through 127 was specified. These flags are 
not valid In standalone mode. 
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IVIACRO-32 
EXAMPLE 

$READEF S 3, FLAGS 



BLISS-32 
EXAMPLE 



$READEF (EFN=3, STATE=FLAGS ) ; 
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$DS_RELBUF 



The $DS_RELBUF macro is used to deallocate buffer space that was 
previously obtained with the $DS_GETBUF macro. The pages deallocated 
will be the pages that were most recently allocated. In user mode, the 
VDS calls the VMS $CNTREG service (see the VAX/VMX System Services 
Reference Manual). 



MACRO-32 $DS_RELBUF_x pagcnt, [retadr], [region] 



BLISS-32 



$DS_RELBUF (PAGCNT = pagcnt, 
[RETADR = retadr], 
[REGION = region]); 



ARGUMENTS 



pagcnt 

Size (number of pages) of buffer space to be deallocated. 

retadr 

Address of a 2-longword array to receive virtual addresses of low and high 
limit of address space deallocated. 

region 

Memory region from which caller wishes buffer space to be deallocated. 
Values are: 

0: buffer allocated from PO space. (Default.) 

1: buffer allocated from PI space. 

2: buffer allocated from system space. 

In standalone mode, this parameter is only relevant if memory 
management is enabled. 
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RETURN 
STATUS 



SS$_NORMAL 
SS$_ACCVIO 

DS$_FRAGBUF 



SS$_ILLPAGCNT 
SS$_PAGOWNVIO 



Buffer space deallocated. 

The "retadr" array cannot be written by the caller. 
User mode only 

The deallocated space was not contiguous. This 
condition could only exist If the specified page count 
was greater the page count specified with the most 
recently Issued $DS_GETBUF macro, since space Is 
always allocated In contiguous chunks in standalone 
mode. Standalone mode only. 

The specified page count was less than 1 . 

In user mode, indicates that a page in the specified 
range is owned by a more privileged access mode. 

In standalone mode, indicates that an attempt was 
made to deallocate more pages than had been 
previously allocated with GETBUF macros. 



MACRO-32 
EXAMPLE 



BOF_LIMITS: 
".QUAD 



$D5_RELBUF #10, BUF_LIMITS ; Release 10 pages. 



BLISS-32 
EXAMPLE: 



OWN 

BUF_LIM1T5 ! VECTOR [ 2 ] ; 

$DS_RELBUF (PAGCNr=10, RETADR=BUF_LIM1TS) ; 
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$DS_SBTTL 



The $DS_SBTTL macro should be used at the beginning of each test and 
subtest, it will perform the following functions: 

• It will generate text containing the test and subtest numbers, along 
with the contents of a programmer-specified character string. This text 
will be included in a .SBTTL l\/IACRO-32 statememt, and will also be 
displayed on the user terminal when the test or subtest is entered and 
the VDS Control Flag TRACE is set. 

• If the macro is at the beginning of a test, a new program section 
(.PSECT) is assigned to the test. (A subtest will be included in the 
PSECT of the test to which it belongs.) 

• The code of the test or subtest will be aligned as specified by the 
programmer. 



MACRO-32 $DS^SBTTL ascii, [align] 



BLISS-32 



Not supported for BLISS-32. 



ARGUMENTS 



asc/7 

Character string representing text to be used as program subtitle and to be 
displayed when VDS TRACE flag is set. 

align 

Desired program section alignment for the test or subtest. Possible values 
are BYTE, WORD, LONG, QUAD, PAGE, or an integer from to 9. If an 
integer is specified, the psect will start at the next address that is a multiple 
of two raised to the power of the integer. 



NOTES 



The $DS_ SBTTL macro should be used in conjunction with the 
$DS_PAGE macro. 



EXAMPLES 



$DS_SBTTL - 

ALIGN = BYTE, - 

ASCII = <READ/WRITE SWAP DATA TEST> 
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$DS_SCBDEF 



The $DS_SCBDEF macro defines (for MACRO-32 programs) symbolic 
names for tiie vector offsets in tlie system control block. For BLISS-32 
programs, these symbols may be referenced without first issuing the 
$DS_SCBDEF macro. 

Symbols defined are: 



SCB$L ZERO 


SCB$L_MACHCK 


SCB$L KNLSTK 


SCB$L_POWER 


SCB$L OPCDEC 


SCB$L_OPCCUS 


SCB$L ROPRAND 


SCB$L RADFMOD 


SCB$L ACCESS 


SCB$L_TRANSL 


SCB$L TBIT 


SCB$L BREAK 


SCB$L COMPAT 


SCB$L_ARITH 


SCB$L CHMK 


SCB$L CHME 


SCB$L OHMS 


SCB$L CHMU 


SCB$L SFTLVLl 


SCB$L SFTLVL2 


SCB$L SFTLVL3 


SCB$L_SFTLVL4 


SCB$L SFTLVL5 


SCB$L_SFTLVL6 


SCBSL SFTLVL7 


5CB$L_SFTLVL8 


SCB$L SFTLVL9 


SCB$L SFTLVLIO 


SCB$L SFTLVLl 1 


SCB$L SFTLVL12 


SCB$L SFTLVL13 


SCB$L SFTLVL14 


SCB$L_SFTLVL15 


SCB$L_TIMER 



MACRO-32 



$DS_SCBDEF [gbl] 



ARGUMENTS gbl 

Can be LOCAL or GLOBAL 



MACRO-32 
EXAMPLE 

$DS_SCBDEF GLOBAL 
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$DS_SECDEF 



The $DS_SECDEF macro is used to declare all of the names of the test 
sections (see Section 3.8.3) of the diagnostic program. This macro must 
appear in every source module that contains tests. The macro is used in 
conjunction with the $DS_SECTION macro. 



MACRO-32 



$DS_SECDEF A, [B, C, D, E, F, G, H, /, J, K, L. M, N, 

0,P] 



BLISS-32 



$DS_SECDEF (A, [B, C, D, E, F, G, H. I, J, K, L, M, N, 

O. P]); 



ARGUMENTS 



A, B, ..., O, P 

List of 1 to 16 test section names. This list must be identical to the list 
included with the $DS_SECTION macro, even if the module in which the 
$DS_SECDEF macro is being placed does not include tests belonging to 
every listed section. 



NOTES 



1 The macro automatically includes the section name DEFAULT at the 
beginning of the section name list. 

2 The test section names must appear in capital letters. 



MACRO-32 
EXAMPLE 



$DS_SECDEF READTESTS, WRITETESTS, SEEKTESTS 



BLISS-32 
EXAMPLE 

$DS_SECDEF (READTESTS, WRITETESTS, SEEKTESTS); 
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$DS_SECTION 



The $DS_SECTION macro is used to declare all of the names of the test 
sections (see Section 3.8.3) of the diagnostic program. This macro must 
appear in the source module that contains the $DS_HEADER macro. 
The $DS_SECTION macro is used in conjunction with the $DS_SECDEF 
macro. 



MACRO-32 $DS SECTION A, [B, C, D, E, F, G, H, I, J, K. L, M, N, 

0,P} 



BLISS-32 $DS_SECTION (A, [B, C, D, E, F, G, H, I, J, K, L, M, /V, 

O, PJ); 



ARGUMENTS A,B,...,0,P 

List of 1 to 16 test section names. This list must be identical to the list 
included with the $DS_SECDEF macro. 



1 The macro automatically includes the section name DEFAULT at the 
beginning of the section name list. 

2 The test section names must appear in capital letters. 



MACRO-32 
EXAMPLE 

$DS SECTION READTESTS, WRITETESTS, SEEKTESTS 



BLISS-32 
EXAMPLE 

$D5_SECTICN (READTESTS, WRITETESTS, SEEKTESTS); 



5-291 



$SETAST 



$SETAST 



The Set AST Enable system service is used to enable and disable the 
delivery of ASTs to the diagnostic program. 



MACRO-32 $SETAST_x enbfig 



BLISS-32 $SETAST (EN BFLG = enbfig); 



ARGUMENTS enbfig 

AST enable indicator. A value of 1 enables AST delivery, while a value of 
disables AST delivery. 



RETURN 
STATUS 



SS$_WASCLR 
SS$_WASSET 



Service successfully completed. AST delivery was 
previously disabled. 

Service successfully completed. AST delivery was 
previously enabled. 



NOTES 



1 For notes on enabling and disabling AST delivery in user mode, refer 
to the VAX/VMS System Services Reference Manual. 



IVIACRO-32 
EXAMPLE 

$SETAST_S #1 ; Enable delivery of ASTs 



BLISS-32 
EXAMPLE 

$SETAST (ENBFLG=0); 'Disable delivery of ASTs 
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The Set Event Flag system service is used to set event flags. (Event flags 
are discussed in Section 4.4.2.) 



MACRO-32 



$SETEF_x efn 



BLISS-32 



$SETEF (EFN = efn); 



ARGUMENTS efn 



Number of the event flag to be set. In user mode, the number may be 
from 1 through 23 or from 32 through 127. In standalone mode, flags 1 
through 64 may be used. 



RETURN 
STATUS 



SS$_WASCLR 

S^$_WASSET 

SS$_ILLEFC 
SS$_UNASEFC 



Service successfully completed. The specified flag 
was previously 0. 

Service successfully completed. Tfie specified flag 
was previously 1 . 

An illegal event flag number was specified. 

in user mode, indicates that the specified common 
event flag (see Section 4.4.2) has not been 
associated with the process issuing the $SETEF 
macro. 

In standalone mode, indicates that an event flag 
from 64 through 127 was specified. These flags are 
not valid in standalone mode. 



MACRO-32 
EXAMPLE 



$SETEF_S #4 ;Set event flag number 4. 



BLISS-32 
EXAMPLE 

$SETEF (EFN=4); !Set event flag number 4. 
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$SETIMR 



The Set Timer system service allows the caller to request that an event flag 
be set, and optionally that an AST be delivered, after a specified amount 
of time has elapsed. 

It is possible to make a number of concurrent timer requests. The caller 
will be notified (via event flag and AST delivery) when each specified time 
inten/al has completed. 



MACRO-32 $SETIMR_x efn, daytim, [astadrj, [reqidtj 



BLISS-32 



$SETIMR (EFN = efn, DAYTIM = daytim, 

[ASTADR = astadr], [REQIDT= reqidt]); 



ARGUMENTS efn 



Number of the event flag to be set after the specified time has elapsed. 
Note: If not specified, defaults to event flag 0, which will cause VDS errors. 

daytim 

Address of quadword containing expiration time. A positive value indicates 
an absolute time at which the timer is to expire. A negative value indicates 
an offset from the current time. In standalone mode, only negative values 
are allowed. (See notes for specifying time.) 

astadr 

Address of the entry mask of an AST routine to be called when the 
specified time interval expires. If not specified, defaults to 0, indicating no 
AST routine is to be called. 

reqidt 

Identification number for the timer request. Default value is 0. A unique 
number may be specified for each timer request, or the same number can 
be assigned to several related requests. This number can be specified 
with the $CANTIM macro to cancel all timer requests having the specified 
number. Also, if an AST routine is specified, the number will be passed to 
the AST routine as the AST parameter. 
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RETURN 
STATUS 



SS$_NORMAL 
SS$_ACCVIO 

SS$_EXQUOTA 



SSSJLLEFC 
SS$$JNSFMEM 

SS$_UNASEFC 



DS$_NOTIMP 



DS$_IPL2HI 



Service successfully completed. 

The expiration time cannot be read by the caller, 

user mode only. 

• In user mode: 

Timer entry quota or AST limit quota exceeded, or 
insufficient system dynamic memory to complete the 
request. 

• In standalone mode: 

The interval clock Is already in use and hence is 
unavailable to this system service. 

An illegal event flag number was specified. 

Insufficient dynamic memory to allocate a timer 
queue entry. 



• In user mode: 

Indicates that the specified common event flag (see 
Section 4.4.2) has not been associated with the 
process issuing the CLREF macro. 

• In standalone mode: 

Indicates that an event flag from 64 through 127 was 
specified. These flags are not valid in standalone 
mode. 

An absolute time value was specified for "daytim." 
Only offset time values are allowed in standalone 
mode. Standalone mode only. 

The current IPL is too high. The IPL must be less 
than 2. Standalone mode only. 



NOTES 



To create a valid argument for the "daytim" parameter, first specify 
the time as an ASCII string, then use the $BINTIM macro to convert 
the ASCII string into the quadw^ord format required by the "daytim" 
parameter. 

You can also specify delta time values when you assemble a macro-32 
program, using two MACRO .LONG directives to represent a time 
value in terms of 100-nanosecond units. The arithmetic is based on the 
following formula: 

1 second = 10 million * 100 nanoseconds 

For example, the following statement defines a delta time value of five 
seconds: 

FIVESECs .LONG -10*1000*1000*5, -1 ; five seconds 

The value 10 million is expressed as 10*1000*1000 for readability. Note 
that the delta time value is negative. 
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If you use this notation, however, you are limited to the maximum 
mmiber of 100-nanosecond units that can be expressed in a longword. 
hi terms of time values, this is somewhat more than seven minutes. 

hi user mode, if the specified absolute time has already passed, the 
timer expires at the next clock cycle (within 10 milliseconds). 

Each time the mterval clock interrupts, the queue of timer requests 
is scanned to determine if any of the specified time intervals have 
expired. In standalone mode, the clock has been set up to interrupt 
every 10 milliseconds when $SETIMR requests are being processed. 

In standalone mode, do not attempt to use the $DS_WAITUS service 
while $SETIMR requests are still pending. 

In a multiprocessing environment, $SETIMR cannot be called from 
within a block of code delineated by the $DS BGNATTACHED and 
$DS_ENDATTACHED macros. 



MACRO-32 
EXAMPLE 



DAYTIME: 



•QUAD 



; Store 64-bit time here. 



.ENTRY AST_RTN, ''M<R2 , R3 , R4> 



AST routine. 



RET 



$SETIMR_S #5, DAYTIME, AST_RTN 
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BLiSS-32 
EXAMPLE 



OWN 

DAYTIME : VECTOR [2]; 



$SETIMR <EFN=8, DAYTIM=DAYTIME) ; 
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$DS_SETIPL 



The Set Interrupt Priority Level system service Is used to change the 
processor's interrupt priorty level (IPL). 

Only level 3 diagnostic programs are allowed to change the processor's 
interrupt priority level. These programs may not change the IPL without 
using this macro. 



MACRO-32 $DS_SETIPL_x level 



BLISS.32 $DS_SETIPL (LEVEL = level); 



ARGUMENTS level 

The level to which the IPL is to be set. 



RETURN 
STATUS 



SS$_NORMAL 



Service successfully completed. 



MACRO-32 
EXAMPLE 

$DS_SETIPL_S #31 ;Set IPL to 31 (decimal), 



BLISS-32 
EXAMPLE 

$DS_SETIPL (I,EVEL=31); t Set IPL to 31 (decimal), 
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$DS^SETMAP 



The Set Adapter Mapping system service of the VDS will set up the 
mapping registers of a bus adapter so that data will be transferred to or 
from the desired physical address space. The service may be used to set, 
clear, validate, or invalidate an adapter's mapping registers. 



MACRO-32 



$DS_SETMAP_x unit, func, phyadr, [mapbasj, 

[bytcnt], [datpth] 



BLISS-32 



$DS_SETM AP (UNIT = unit, FUNC = func, 

PHYADR = phyadr, 
[MAPBAS = mapbas], 
[BYTCNT = bytcnt], 
[DATPTH = datpth]); 



ARGUMENTS unit 



Logical unit number of the device to be tested. 

func 

Function code indicating the function to be performed. Function codes are 
listed in Note 1. 

phyadr 

Address of a 2-longword array that contains the physical addresses of the 
beginning and the ending of the physical address space from which or to 
which data is to be transferred. Commonly, this is the "phyadr" array 
filled in by the $DS_GETBUF service. The value specified as the ending 
address is used to validate the "b3rtcnt" parameter. 

mapbas 

This argument is used to optionally select the first (lowest addressed) 
map register to be employed in mapping virtual program addresses to 
physical memory addresses. The service will start with the map register 
specified and set up (or clear) enough map registers to map the address 
range indicated by "phyadr". 

For a MASSBUS operation, the argument must be a value from to 255 
(decimal), where selects the first map register, 1 selects the second, and 
so on. TTie MBA Virtual Address Register will be automatically set up to 
point to the specified map register. 

For a UNIBUS operation, the argument must be a value from to 495 
(decimal), where selects the first map register, 1 selects the second, and 
so on. 

The default value is 0. 
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For descriptions of address translation in bus adapters, refer to the VAX 
Hardware Handbook. 

bytcnt 

Number of bytes composing a data transfer. For MASSBUS operation, the 
2's complement of this value is stored in the MBA byte counter. Maximum 
value allowed is 65535 (decimal). 

For both MASSBUS and UNIBUS operation, this value is used when 
setting up map registers — enough pages are mapped to handle the 
number of bytes specified. 

The default value is 0. If the default is used, one page (512 bytes) is 
mapped. 

datpth 

Value indicating the UNIBUS data path. The default is 0, indicating the 
direct data path. Values from 1 through 15 may be specified to select one 
of the buffered data paths. This field is ignored if the UNIBUS adapter 
does not support buffered data paths. 



RETURN 
STATUS 



DS$_NORMAL 

DS$_ERROR 

DS$_IHWE 



$DS_PROGERR 



Service successfully completed. 

The specified logical unit number is too large. 

Initial hardware error. A hardware error was detected 
in the bus adapter before the specified function 
was performed. The function was not performed. 
Call the $DS_CHANNEL service, specifying the 
CHC$_STATUS function to determine the error type. 

An invalid function code was specified. 

The byte count specified is too large to be mapped 
starting at the specified map register. Lower the 
byte count or lower the starting map register number. 

The byte count specified will not fit into the buffer 
limits indicated by "phyadr." 



NOTES 



1 Function Codes 

Following is a list of valid function codes. For MACRO-32, these codes 
are defined by the $DS_CHMDEF macro. 

• CHM$_INVALIDATE - Clear the "valid" bits for all map registers 
in the bus adapter to which the device unit specified by "unit" is 
attached. 

• CHM$_MFWDN — Set up map registers for a forward transfer 
according to "phyadr," "mapbas," and "bytcnt" parameters, and 
set the "valid" bit in each register used. Do not invalidate any 
registers. If MASSBUS, load MBA virhial address register and 
MBA b5rte counter. 
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CHM$_MFWDNO — Set up map registers for a forward transfer 
accordmg to "phyadr," "mapbas," ai\d "bytcnt" parameters, and 
set the "valid" bit in each register used. Do not invalidate any 
registers. Indicate that a byte offset transfer will be performed 
(UNIBUS only). 

CHM$_MFWDV — Invalidate all map registers. Set up map 
registers for a forward transfer according to "phyadr," "mapbas," 
and "bytcnt" parameters, and set the "valid" bit in each register 
used. If MASSBUS, load MBA virtual address register and MBA 
byte counter. 

CHM$_MFWDVO — Invalidate all map registers. Set up map 
registers for a forward transfer according to "phyadr," "mapbas," 
and "bytcnt" parameters, and set the "valid" bit in each register 
used. Indicate that a byte offset transfer will be performed 
(UNIBUS only). 

CHM$_MREVN — Set up map registers for a reverse transfer 
according to "phyadr," "mapbas," and "bytcnt" parameters, and 
set the "valid" bit in each register used. Do not invalidate any 
registers. If MASSBUS, load MBA virtual address register and 
MBA byte counter. 

CHM$_MREVNO — Set up map registers for a reverse transfer 
according to "phyadr," "mapbas," and "bytcnt" parameters, and 
set the "valid" bit in each register used. Do not invalidate any 
registers. Indicate that a byte offset transfer will be performed 

(UNIBUS only). 

CHM$_MREW — Invalidate all map registers. Set up map 
registers for a reverse transfer according to "phyadr," "mapbas," 
and "bytcnt" parameters, and set the "valid" bit in each register 
used. If MASSBUS, load MBA virtual address register and MBA 
byte counter. 

CHM$_MREWO — Invalidate all map registers. Set up map 
registers for a reverse transfer according to "phyadr," "mapbas," 
and "b3rtcnt" parameters, and set the "valid" bit in each register 
used. Indicate that a byte offset transfer will be performed 
(UNIBUS only). 

CHM$_NFWDN — Do not alter map register contents. If 
MASSBUS, load MBA virtual address register and MBA byte 
counter for forward transfer. 

CHM$_NREVN — Do not alter map register contents. If 
MASSBUS, load MBA virtual address register and MBA byte 
counter for reverse transfer. 

In a multiprocessing environment, $DS_SETMAP cemnot 
be called from within a block of code delineated by the 
$DS_BGNATTACHED and $DS_ENDATTACHED macros. 
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MACRO-32 
EXAMPLE 

BUF_SIZE = 1024 
LOG_UNIT: .BLKL 1 

BUFFER: .BLKQ 1 



$DS_SETMAP_S LOG_UNIT, #CHM$_MFWDV, BUFFER, , #BUF_SIZE 



BLISS-32 
EXAMPLE 



LITERAL 

BUF_SIZE = 1024; 

OWN 

LOG_UNIT : VECTOR, 
BUFFER : VECTOR [ 2 ] ; 



$DS_SETMAP (UNIT=.LOG_UNIT, FUNC=CHMS_MFWDV, 

PHYADR=BUFFER, BYTCNT=BUF_SIZE) ; 
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The Set Protection on Pages system service aliows a program to ciiange 
the protection code associated with one or more pages of virtual memory. 



MACRO-32 



$SETPRT inadr, [retadr], [acmode], prot, [prvprt] 



BLISS-32 



$SETPRT (INADR = inadr, [RETADR = retadr], 
[ACMODE = acmode], PROT = prot, 
[PRVPRT =^ prvprt]); 



ARGUMENTS 



inadr 

Address of a 2-longword array containing the starting and ending virtual 
addresses of the pages for v^fhich the protection code is to be changed. 
Specifying the same value for the starting and ending addresses wdll cause 
the protection of one page to be changed. Only the virtual page number 
portion of the address is used; the low-order nine bits are ignored. 

retadr 

Address of a 2-longword array to receive the starting and ending virtual 
addresses of the pages that had their protections changed. See Note 2. 

acmode 

Access mode on behalf of which the request is being made. The specified 
access mode is maximized with the access mode of the caller. The result 
must be equal to or more privileged than the access mode of the owner of 
the pages being changed. 

This parameter is ignored in standalone mode. 

prot 

New protection, in bits through 3. S5nnbolic names for the various page 
protection codes are described by the $PRTDEF macro which is defined in 
STARLET.MLB. 

prvprt 

Address of a byte to receive the protection previously assigned to the last 
page whose protection was changed. Useful if only one page was changed. 
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RETURN 
STATUS 



SS$_NORMAL 
SS$_ACCVIO 



SS$_EXQUOTA 

SS$JVPROTECT 
SS$_LENVIO 



SS$_NOPRIV 
SS$_PAGOWNVIO 

DS$ PROGERR 



Service successfully completed. 



• User mode: 

— The Input address array cannot be read by 
the caller, or the output address array or 
the byte to receive the previous protection 
cannot be written by the caller. 

— An attempt was made to change the 
protection of a nonexistent page. 

• Standalone mode: 

The specified address range was in the reserved 
virtual address space (COOOOOOO to FFFFFFFF). 

The process exceeded Its paging file quota while 
changing a page in a read-only private section to a 
read/write page. User mode only. 

The specified protection code has a numeric value 
of 1 or is greater than 15. User mode only. 

In user mode, a page in the specified range is 
beyond the end of the program or control region. 

In standalone mode, a page in the specified range 
is beyond the end of the program, control, or system 
region. 

A page in the specified range is in the system 
address space. User mode only. 

Page owner violation. An attempt was made to 
change the protection on a page owned by a more 
privileged access mode. User mode only. 

The specified address range was improperly 
formatted. Standalone mode only. 



NOTES 



In standalone mode, setting page protection is only meaningful if 
memory management has been enabled. 

If an error occurs v^hile changing page protections, the return array, if 
specified, will contain the start and ending address of the pages that 
were changed before the error occurred. If no pages were changed, the 
return address array will contain a minus one (-1). 
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IVIACRO-32 
EXAMPLE 

ADDR FLANGE: .BLKQ 1 



$SETPRT INADR=ADDR RANGE, PROT=#PRT$C_UW 



BLISS-32 
EXAMPLE 



OWN 

ADDR_tlANGE : VECTOR [2]; 



$SETPRT (INADR=ADDR_RANGE, PROT=PRT$C_UW) ; 
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$DS_SETVEC 



The Set Exception or Interrupt Vector system service is used to load an 
exception or interrupt vector with the address of a service routine (see 
Note 3). 

Only level 3 diagnostic programs may use the $DS_SETVEC macro. 
Vector contents may not be changed by any means other than the use of 
this macro. 



MACRO-32 



$DS_SETVEC_x vector, srvadr, [code] 



BLISS-32 



$DS_SETVEC (VECTOR = vector, SRVADR = srvadr, 
[CODE = code]); 



ARGUMENTS 



vector 

The vector address, relative to the base of the System Control Block (SCB). 
Refer to the VAX Architecture Haitdbook for a list of vector addresses in the 
SCB. See Note 1. 

srvadr 

The address of a service routine which is to receive control when an 
exception or interrupt is delivered through the specified vector. The 
address must be on a longword boundary. 

cocfe 

Used to indicate the stack on which the event is to be serviced. 
Can be or 1. (The default is 0.) 

• If 0, service the event on the kernel stack unless already running on the 
interrupt stack, in which case service on the interrupt stack. Behavior 
of the processor is undefined for a "kernel stack not valid" exception 
with this code. 

• If 1, service the event on the interrupt stack. If the event is an 
exception, raise the IPL to IF (hexadecimal). 

The value specified for this parameter is loaded into bits <1:0> of the 
specified vector. 
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RETURN 
STATUS 



DS$_NORMAL 
DS$_IVADDR 

DS$_IWECT 

DS$_ICBUSY 



Service successfully completed. 

Address specified for "srvadr" routine does not start 
on a longword boundary. 

Address specified for "vector" is not a valid vector 
address. 

Thie caller specified ttie interval clocl^'s vector, and 
the inten/al clock was already active. 



NOTES 



1 The old contents of the specified vector are returned in Rl. 

2 When setting device interrupt vectors, remember that the SCB is 
several pages long. The page on which a particular device interrupt 
vector resides is determined by both the bus adapter(s) to which the 
device is attached and the processor being used. 

For instance, to find the SCB offset for a particular UNIBUS device's 
vector address, read HP$W_ VECTOR in the device's p-table, then 
OR this value with the contents of HP$W_ VECTOR in the p-table 
associated with EACH adapter existing between the device and the 
processor. The number and t3^e of adapter depend on the processor 
type. (The device's p-table contains the actual UNIBUS vector, and the 
adapters' p-tables contain relative offsets into the SCB for the bases of 
the vector areas for the adapters.) It therefore becomes obvious that 
referencing device vectors in the SCB will cause a diagnostic program 
to become processor-dependent. Using the $DS_CHANNEL service 
for I/O operations eliminates the need to load SCB vectors and thus 
keeps diagnostic programs processor-independent. 

3 In a multiprocessing environment, $DS_SETVEC cannot be called from 
within a block of code delineated by the $DS_BGNATTACHED and 
$DS_ENDATTACHED macros. 
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MACRO-32 
EXAMPLES 

$DS_SETVEC_S VECTADDR, SERV_RTN 

$DS_SETVEC_S #4, MCHK_SERVICE 



BLISS-32 
EXAMPLE 

$DS_SETVEC (VECTOR=. VECTADDR, SRVADR=SERV_RTN, C0DE=1 ) ; 
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The Show Channel Status system service of the VDS will display on the 
user's terminal the contents of internal bus adapter registers. This service 
should be used whenever the $DS_CHANNEL or $DS_SETMAP services 
detect adapter faults. 

The display will consist of the name of each register, the mnemonic name 
of each bit field within the register, and the current value of each bit field. 

This service is only available to level 3 diagnostic programs. 



MACRO-32 



$DS_SHOCHAN_x unit 



BLISS-32 



$DS_SHOCHAN (UNIT = unit); 



ARGUMENTS unit 



Logical unit number of device currently being tested. Adapter to which this 
unit is attached will be the one whose registers are displayed. 



RETURN 
STATUS 



$DS_NORMAL 
$DS_ERROR 



Service successfully completed. 
Logical unit number is too large. 



NOTES 



It may be useful to include the $DS_SHOWCHAN macro in an error 
reporting routine (refer to the error reporting macros, $DS_ERRxxxx). 



MACRO-32 
EXAMPLE 



$DS SHOCHAN 5 LOG UNIT 



; Display adapter status. 



BLISS-32 
EXAMPLE 

$DS_SHOCHAn (UNIT=. L0G_UN1T ) ; 
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$DS^SHOWIDLE 



In a multiprocessor environment, use the Show Idle Processors service to 
determine which attached processors are currently executing in the idle 
state. Attached processors are placed in the idle state when: 

• The $DS_BOOTATTACHED service has completed bootstrapping the 
processor. 

• An attached process, delimited by the $DS_BGN ATT ACHED and 
$DS_ENDATTACHED macros, finishes executing. 

• A multiprocessor diagnostic program Is stopped by a control-C, 
breakpoint, or an exception. 



MACRO-32 



$DS_SHOWIDLE_x bitmap 



BLISS-32 



$DS_SHOWIDLE (BITMAP = bitmap); 



ARGUMENTS 



bitmap 

Address of the longword to receive a bitmap indicating which attached 
processors are currently executing in the idle state. There are 32 bits (0 
through 31); each bit corresponding to a logical unit number. You need to 
look at the bits that correspond to logical unit numbers actually associated 
with attached processors. (See Note 1.) 



RETURN 
STATUS 



DS$_NORMAL 



Service successfully completed. 



NOTES 



One method for using this service is to create a bit mask. Each time 
you issue a $DS_GPHARD call and receive the address of a p-table 
for an attached processor, set the bit in the mask corresponding 
to the logical unit number for that p-table. When you call the 
$DS_SHOWIDLE service, test only the bits that are set in the mask 
you created. 
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$DS_SHOWIDLE 



MACRC 


)-32 






EXAMPLE 






IDLE MASK: 




LONG 





IDLE_PROC: 




LONG 






$DS SHOWIDLE_S (IDLE_PROC) ; Get idling processors. 
CMPL IDLE_MASK, IDLE~PROC ; Are they all idling? 
BEQL 300$"" ; Yes, branch. 



BLISS-32 
EXAMPLE 



$DS_SHOWIDLE (BITMAP=IDLE_PROC ) ; ! Get idling processors. 

IF 7.IDLE_MASK NEQ .IDLE_PROC) ! If any are not idling then. 

THEN 
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$DS_STARTATTACHED 



In a multiprocessor environment, you can use tlie Start Attached CPU 
system service to cause an attached processor to begin executing 
a section of code (enter the running state). Before you can use 
this service, you must bootstrap the specified processor with the 
$DS_BOOTATTACHED service. 

You must delimit the section of code to be executed with the 
$DS_BGNATTACHED and $DS_ENDATTACHED program structure 
macros. The service, in conjunction with these macros, causes 
the specified processor to leave the idle state (entered via the 
$DS_BOOTATTACHED service) and start executing the code delimited 
by the macros. When it finishes executing, the processor re-enters the 
idle state. (Refer to the description of the $DS_BGNATTACHED and 
$DS_ENDATTACHED macros for details.) 



IVIACRO-32 $DS_STARTATTACHED_x unit, start_addr 



BLISS-32 



$DS_STARTATTACHED (UNIT = unit, 

START_ADDR = startjaddr); 



ARGUMENTS unit 



Logical unit number of the processor to be bootstrapped. 

Startjaddr 

Address of the code to be executed in the attached processor. 
This argument must be the address of the code generated by a 
$DS_BGNATTACHED macro. 



RETURN 
STATUS 



DS$_NORMAL 

DS$JLLUNIT 

DSSJNVCPU 



Service successfully completed. 

The specified logical unit number Is too large. 

Can't start ttie specified processor. May 
mean the processor doesn't exist or the 
processor was not executing in its idle state (see 
$DS_BOOTATTACHED). 
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MACRO-32 
EXAMPLE 



$DS BGNATTACHED ROUTINEl 



$DS ENDATTACHED 



$DS_STARTATTACHED_S LOG_UNIT, ROUTINEl 



BLISS-32 
EXAMPLE 



$DS_BGNATTACHED (R0UTINE_NAME=R0UTINE1 ) ; 



$DS_ENDATTACHED ; 



$DS_STARTATTACHED (UNIT = .LOG_UNIT, START_ADDR=R0UTINE1) ; 
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$DS_$STORE 



The $DS_$STORE p-table descriptor macro is used to load ttie 
contents of the "value register" (see Section 3.2.3.3) into a field of 
the p-table being built. The macro can be used to store values read 
by the $DS_$DECIMAL, $DS_$OCTAL, $DS_$HEX, $DS_$STRING, 
or $DS_$LOGICAL statements, or generated by the $DS $LITERAL, 
$DS_$FETCH, $DS_$COMPLEMENT, or $DS_$CASE statements. It can 
also be used to facilitate temporary storage. A value can be stored in the 
p-table temporarily while the value register is needed for something else, 
then later restored with the $DS_$FETCH statement. This macro does not 
change the contents of the value register. 



MACRO-32 



$DS_$STORE offset, pos, size 



BLISS-32 



$DS_$STORE (OFFSET = offset, POS = pos, 
SIZE = size); 



ARGUMENTS 



offset 

The byte offset into the p-table of the field into which the contents of the 
value register are to be placed. 

pos 

Bit position of the field, relative to the beginning of the byte specified by 
"offset." If the field starts on a byte botindary, this value will be 0. 

Size 

Number of bits making up the field. Tlie size cannot be larger than 32. 



NOTES 



1 Code generated by macro (shown in Macro-32; Bliss-32 is equivalent): 



.BYTE '^xee 

.WORD offset 

. BYTE pos 

.BYTE size 



; Beginning of STORE directive 

; Word data structure offset 

; Bit position in word 

; Bit field size 



MACRO-32 
EXAMPLES 

$DS_$STORE OFFSET=HP$L_RK611_CSR, POS=0, SIZE=32 
$DS_$STORE <'^X40>, 0, 32 
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BLISS-32 
EXAMPLES 



$DS_$STORE (OFFSET=%FIELDEXPAND(HP$L_RK611_CSR,0) , 
P0S=%FIELDEXPAND(HP$L_RK611_CSR, 1 ) , 
SI ZE=%FIELDEXPAND ( HP$L_RK6 1 1_CSR, 2 ) ) ; 

$DS_$STORE (OFFSET=%X'40', POS=0 , SIZ=32); 
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$DS_STRING 



The $DS_STRING macro can be used to generate a quadword descriptor 
(see Section 5.3) for a given ciiaracter string. In i\/IACRO-32 programs, 
.ASCIC and .ASCiZ formats for the string may aiso be generated. This 
enables the programmer to reference the same string in any of the three 
formats. 



MACRO-32 $DS_STRING < text>, [labeH], [Iabel2] 



BLISS-32 



$DS.STRING ('text'); 



ARGUMENTS text 



Character string for which a quadword descriptor is to be constructed. 

labell 

Label to be placed at the .ASCIC construction of the character string. (This 
parameter may not be referenced by keyword.) 

Iabel2 

Label to be placed at the .ASCIZ construction of the character string. (This 
parameter may not be referenced by ke)mrord.) 



NOTES 



1 The quadword descriptor will be constructed at the current PC. It may 
be accessed by placing a label at the macro call, as illustrated in the 
example. 



MACRO-32 
EXAMPLE 

MSG_LABEL: 

$DS STRING - 



<THIS IS A MESSAGE. >, 
MSG_LABEL1, - 
MSG LABEL2 



(•Create descriptor for string. 



Include label for .ASCIC 
Include label for .ASCIZ 
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$DS_STRING 



BLISS-32 
EXAMPLE 



BIND 

MSG LABEL = $DS_5TRING (THIS IS A MESSAGE.)! 
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$DS_$STRING 



The $DS_$STRING p-table descriptor macro is used to read a string from 
an ATTACH command line, if tlie string exists on tfie ATTACH command 
iine, it wiii be used; otiierwise, tlie prompting message will be displayed. 
Tlie string read from tlie command line is compared against a list of 
valid strings, and tlie number of the match string (0, 1 , 2, and so on, In 
the order given) is returned in the value register. This can be used, for 
example, to determine if a DZ-1 1 line card to be tested is EIA or 20MA, by 
the statement $DS_$STRING (Line type, EIA, 20Mfi^ which would return 
if the response was EIA, or 1 if the response was 20MA. 



MACRO-32 $DS.$STRING <prompt_>, < string, [string,... ]_> 



BLISS-32 



$DS_$STRING ('prompt', 'string', ['string', ...]); 



ARGUMENTS 



prompt 

Character string to be used as a prompting message. 

String 

A character string with which the input string is to be compared. The 
number of the first string that exactly matches the input will be returned. 



NOTES 



Code generated by macro (shown in Macro-32; Bliss-32 is equivalent): 



.BYTE '^XSS 
.ASCIC \prompt\ 
.ASCIC \stringl\ 



.ASCIC \stringn\ 
.BYTE 



; Beginning of STRING prompt 
; Prompt string 
; ASCIC string 1 

; ASCIC strings 

; ASCIC string n 
; List terminator 



MACRO-32 
EXAMPLES 

$DS$STRING <Module type>, «EIA>, <20MA» 
$DS$STRING PROMPT=<Node type>, STRINGS=<780,750, 730> 
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$DS_$STRING 



BLISS-32 
EXAMPLES 

$DS_$5TRING ('Module type' , 'EIA', '20MA'); 
$DS_$STRING ('Node type', '780', '750', '730'); 



5-319 



$DS_SUMMARY 



$DS_SUMMARY 



The Print Summary system service will cause the diagnostic program's 
summary routine to be executed. Summary routines are discussed in 
Section 3.7. Note that the summary routine will also be executed when 
the $DS_ENDPASS service is called, if the requested number of program 
passes have been executed. 



MACRO-32 



$DS_SUMMARY_x 



BLiSS-32 



$DS^SUMMARY; 



RETURN 
STATUS 



No status returned. 



MACRO-32 
EXAMPLE 

$DS SUMMARY S 



BLISS-32 
EXAMPLE 

$DS_SUMMARY; 
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$UNWIND 



The Unwind Call Stack system service allows a condition handler to 
"unwind" the procedure call stack to a specified depth. "Unwinding" is 
the process of stepping through a specified number of call frames on the 
stack so that when the condition handler returns, the specified call frame 
will be used instead of the one placed on the stack when the condition 
handler was called. In other words, the normal execution flow is altered. 
Optionally, an address can be specified that will be placed in the return 
PC argument of the call frame that was stepped to. 

For further discussion of unwinding, refer to sections on condition handling 
in the VAXNMS System Services Reference Mar)ual. 



MACRO-32 



$UNWIND_x [depadr], [newpc] 



BLiSS-32 



$UNWIND ([DEPADR = depadr], [NEWPC = newpc]); 



ARGUMENTS 



depadr 

Address of a longword indicating the depth to which the stack is to be 
unwound. A depth of indicates the call frame that was active when 
the condition occurred (the fran^e that would normally be used when the 
condition handler returns), 1 indicates the caller of that frame, 2 indicates 
the caller of the caller of the frame, and so on. If the depth is specified as 
or less, no unwind occurs and a successful status code is returned. If no 
value is specified for this parameter, the unwind is performed to the caller 
of the frame that established the condition handler. 

newpc 

Address to be given control when the unwind is complete. This value is 
placed in the return PC argument of the call frame that is stepped to. If no 
value is specified for this parameter, the return PC argument is not altered. 



RETURN 
STATUS 



SS$_NORiVIAL 
SS$_ACCVIO 

SS$_INSFRAME 
SS$_NOSIGNAL 
SS$_UNWINDING 



Service successfully completed. 

The call stack Is not accessible to ttie caller. This 
condition is detected when the call stack is scanned 
to modify the return address. User mode only. 

There are insufficient call frames to unwind the 
specified number of frames. 

No signal for an exception condition is currently 
active. 

An unwind Is already in progress. 
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$UNWrND 



NOTES 



The actual unwind does not occur when the service is called. The 
service simply modifies the return addresses in the call frames so that 
when the condition handler returns, an "unwind" procedure is called 
from each frame that is being unwound. 



IVIACRO-32 
EXAMPLE 



In this example, the $UNWIND will cause the return PC of the call 
frame created by the CALLS ROUTINEl instruction to be replaced by 
OUTADDR, and the RET instruction on the condition handler will cause 
that call frame to be referenced. 



ROUTINEl: 



MOVAB COND_HNDLR, (FP) 



CALLS ROUTINE 2 



R0UTINE2 : 



(Condition occurs.) 



RET 
COND HNDLR: 



MOVL #1, DEPTH 
$UNWIND_S DEPTH, OUTADDR 



RET 



OUTADDR: 
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BLISS-32 
EXAMPLE 



$UNWIND 



ROUTINE ROUTINEl = 
BEGIN 
.FP = COKD_HNDLR; 



R0UTINE2 ( ) ; 



END; 

ROUTINE ROUTINE 2 
BEGIN 



(Condition occurs.) 



END; 



ROUTINE COND_HNDLR = 
BEGIN 



DEPTH = 1; 

$UNWIND (DEPADR=DEPTH, NEWPC=ERR0RS+2 ) ; 



END; 



ROUTINE ERRORS 
BEGIN 



END; 
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$WAITFR 



The $WAITFR macro calls a system service that will wait until a 
specified event flag is set before returning. Event flags are discussed 
in Section 4.4.2. If the specified flag is already set, the service routine 
returns immediately. Otherwise, control is not returned to the caller until 
the flag has been set. 



IVIACRO-32 



$WAITFR_x efn 



BLISS-32 



$WAITFR (EFN = efn); 



ARGUMENTS 



efn 

Number of the event flag to wait for. 



RETURN 
STATUS 



SS$_NORMAL 

SS$_ILLEFC 

SS$_UNASEFC 



Service successfully completed. 

An illegal event flag number was specified. 

In user mode, indicates tfiat tfie specified common 
event flag (see Section 4.4.2) has not been 
associated witfi tfie process Issuing tfie $SETEF 
macro. 

In standalone mode, indicates tfiat an event flag 
from 64 througfi 127 was specified. These flags are 
not valid in standalone mode. 



NOTES 



While the system service routine is waiting for the event flag to be 
set, ASTs can interrupt the service. Program control will return to 
the $WAITFR system service after execution of the AST routine has 
completed. 
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$WAITFR 



MACRO-32 
EXAMPLE 

$WAITFR_S #4 



BLISS-32 
EXAMPLE 

$WAITFR (EFN=5); 
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$DS_WAITMS 



The Millisecond Wait system service is used to create a delay of a 
specified number of milliseconds. Wlien the service routine is called, 
control is not returned to the caller until the requested amount of time 
has elapsed (unless an asynchronous event occurs that causes a routine 
containing a $CANTII\/I or $DS_CANWAIT macro to be executed; see 
Note 1 .) 



MACRO-32 $DS_WAITIVIS_x time, [tag] 



BLISS-32 



$DS_WAITMS (TIME = time, [RETTIM = tag]); 



ARGUMENTS 



time 

Length of delay in time units. One time unit equals 10 milliseconds. 

tag 

Address of longword to receive amount of unused time, if delay was 
canceled before all requested time was used up (see Note 1). 



RETURN 
STATUS 



SS$_NORMAL 
DS$_PROGERR 



SS$_EXQUOTA 



Service successfully completed. 

A value less than the overhead to complete the 
system service was specified for the "time" 
parameter. Note: the overhead refers to the machine- 
dependerit amount of time required to execute this 
system service. 

The interval clock is already in use and hence is 
unavailable to this system sen/ice. 



NOTES 



1 If an asychronous event (AST delivery or hardware interrupt) occurs, 
and the routine handling the AST or interrupt issues a $CANTIM 
or $DS_CANWAIT macro, the $WAITMS service will, on regaining 
program control after return from the event handler, store the unused 
delay time in the address specified by "tag" and return control to the 
caller. 

2 In a multiprocessing environment, $DS_WAITMS cannot be called 
from within a block of code delineated by the $DS_BGNATTACHED 
and $DS_END ATTACHED macros. 

3 $DS_WAITMS cannot be used if the IPL is greater than 2 and $SETIMR 
requests have been issued and are still pending. 
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$DS_WAITMS 



MACRO-32 
EXAMPLE 

$DS_WAITMS_S #100, TIME_IiEFT 



BLISS-32 
EXAMPLE 

SDS_WAITMS (TIME=200, RETTIM=TIME_LEFT ) ; 
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$DS_WAITUS 



The Microsecond Wait system service is used to create a delay of a 
specified number of microseconds. Wfien the service routine is called, 
control is not returned to the caller until the requested amount of time has 
elapsed (unless an asynchronous event occurs which causes a routine 
containing a $CANTIM or $DS_CANWAIT macro to be executed; see 
Note 1.) 

This macro may only be used by level 3 diagnostic programs. 



MACRO-32 



$DS_WAITUS_x time, [tag] 



BLISS-32 



$DS_WAITUS (TIME = time, [RETTIM = tag]); 



ARGUMENTS 



time 

Length of delay in time units. One time unit equals 10 microseconds. 

tag 

Address of longword to receive amount of unused time, if delay was 
canceled before all requested time was used up (see notes). 



RETURN 
STATUS 



SS$_NORMAL 
DS$_PROGERR 



SS$_EXQUOTA 



Service successfully completed. 

A value less than the overhead to complete the 
system service was specified for the "time" 
parameter. Note: the overhead refers to the machine- 
dependent amount of time required to execute this 
system service. 

• In user mode: 

Timer entry quota or AST delivery quota exceeded, 
or insufficient dynamic memory space. 

• In standalone mode: 

The inten/al clock is already in use and is therefore 
unavailable to this system service. 
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$DS_WAITUS 



NOTES 



If an asychronous event (AST delivery or hardware interrupt) occurs, 
and the routine handling the AST or interrupt issues a $CANTIM or 
$DS_CANWAIT macro, the $DS_WAITUS service will, on regaining 
program control after return from the event handler, store the unused 
delay time in the address specified by "tag" and return control to the 
caller. 

Do not use the $DS_WAITUS service if $SETIMR requests have been 
issued and are still pending. 

For information on using this service in a multiprocessor environment, 
refer to Section 4.6. 



MACRO-32 
EXAMPLE 



$DS_WAITUS_S #50, TIME_LEFT 



BLISS-32 
EXAMPLE 

$DS_WAITUS (TIME=40, RETTIM=TIME_LEFT ) ; 
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$WAKE 



The Wake system service reactivites a process that is in hibernation as a 
result of execution of the $HiBER system service. 



MACRO-32 



$WAKE_x [pidadr], [prcnam] 



BLISS-32 



$WAKE ([PIDADR = pidadr], [PRCNAM = prcnam]); 



ARGUMENTS 



pidadr (user mode only) 

Address of a longword containing the process indentification of the process 
to be awakened. 

prcnam (user mode only) 

Address of a character string descriptor (see Section 5.3) pointing to the 
process name string. 

Refer to the VAX/VMS System Services Reference Manual for details on the 
interpretation of these parameters. 



RETURN 
STATUS 



SS$_NORMAL 
SS$_ACCVIO 

SS$_IVLOGNAM 
SS$_NONEXPR 

SS$_NOPRIV 



Service successfully completed. 

The name string or string descriptor cannot be read 
by the caller, or the process id number cannot be 
written by the caller. User mode only. 

The process name string is invalid. 

Warning. The specified process does not exist, or 
an invalid process id was specified. 

The caller's process does not have the privilege 
required for waking the specified process. 



NOTES 



1 In standalone mode, the only meaningful use of this macro is to place it 
in an event handler that will be executed while the diagnostic program 
is in hibernation. This will awaken the program so that it may continue 
executing. 

2 In a multiprocessing environment, $WAKE cannot be called from 
within a block of code delineated by the $DS_BGNATTACHED and 
$DS_ENDATTACHED macros. 
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MACRO-32 
EXAMPLE 



$WAKE S 



BLISS-32 
EXAMPLE 

$WAKE ( ) ; 
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$WFLAND 



The $WFLAND macro calls a system service that will wait until a specified 
group of event flags is set before returning. Event flags are discussed 
in Section 4.4.2. All of the event flags must be in the same event flag 
cluster. If the specified flags are already set, the service routine returns 
immediately. Otherwise, control is not returned to the caller until all 
specified flags have been set. 



IVIACRO-32 



$WFLAND_x efn, mask 



BLISS-32 



$WFLAND (EFN = efn, MASK = mask); 



ARGUMENTS efn 



Number of any event flag in the cluster being used. 

mask 

32-bit mask in which bits set to 1 indicate event flags that must be set 
before the system service returns. 



RETURN 
STATUS 



SS$_NORMAL 

SS$JLLEFC 

SS$_UNASEFC 



Service successfully completed. 

An illegal event flag number was specified. 

In user mode, indicates ttiat the specified common 
event flag (see Section 4.4.2) has not been 
associated with the process Issuing the macro. 

In standalone mode, indicates that an event flag 
from 64 through 127 was specified. These flags are 
not valid in standalone mode. 



NOTES 



While the system service routine is wailing for the event flags to be 
set, ASTs can interrupt the service. Program control will return to 
the $WFLAND system service after execution of the AST routine has 
completed. 
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MACRO-32 
EXAMPLE 

SWFLAND_S #0, FLAG_MASK 
$WFLAND_S #0, #OO00OOF0 



BLISS-32 
EXAMPLE 



$WFLAND (EFN=0, MASK==.FLAG_MASK) ; 
$WFIiAND {EFN=0, MASK=%X' OOOOOOFO ' ) ; 
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$WFLOR 



The $WFLOR macro calls a system service that will wait until any one of 
a specified group of event flags is set before returning. Event flags are 
discussed in Section 4.4.2. All of the event flags must be in the same 
event flag cluster. If any one of the specified flags is already set, the 
service routine returns immediately. Otherwise, control is not returned to 
the caller until one of the specified flags has been set. 



MACRO-32 



$WFLOR_x efn, mask 



BLISS-32 



$WFLOR (efn, mask); 



ARGUMENTS efn 



Number of any event flag in the cluster being used. 

mask 

32-bit mask in which bits set to 1 indicate event flags that are to be tested 
by the system service. 



RETURN 
STATUS 



SS$_NORMAL 

SS$_ILLEFC 

SS$_UNASEFC 



Service successfully completed. 

An Illegal event flag number was specified. 

In user mode, indicates ttiat the specified common 
event flag (see Section 4.4.2) has not been 
associated with the process issuing the macro. 

In standalone mode, indicates that an event flag 
from 64 through 127 was specified. These flags are 
not valid in standalone mode. 



NOTES 



While the system service routine is waiting for an event flag to be 
set, ASTs can interrupt the service. Program control will return to 
the $WFLOR system service after execution of the AST routine has 
completed. 



5-334 



$WFLOR 



MACRO-32 
EXAMPLE 

$WFLOR_S #0, FLAG_MASK 
$WFLOR_S #0, ♦OOOOOOFO 



BLiSS-32 
EXAMPLE 

$WFLOR (EFN=0, MASK=FLAG_MASK) ; 
SWFLOR (EFN=0, MASK=%X' OOOOOOFO ') ; 
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$XABFHC 



The $XABFHC will allocate the File Header Characteristics Extended 
Attribute Block (FHC XAB), which is an optional data structure used by 
RMS. If the $XABFHC macro is used, and if a pointer to the FHC XAB is 
specified in the FAB, then the $OPEN operation will load the FHC XAB 
with file header characteristics obtained from the header of the file that 
was opened. 

Besides allocating the XAB, the $XAB macro also defines symbols for 
each XAB field. Symbols are of the form XAB$datatype_fieidname, where 
"datatype" is a data type specifier listed in Table 6-1. 



MACRO-32 



$XABFHC 



BLISS-32 



$XABFHC; 



NOTES 



FHC XAB Fields 

Following are the FHC XAB fields filled in by VDS RMS. Refer to the 
VAX/VMS RMS Reference Manual for fields filled in by VMS RMS. 

ATR — Record attributes. Same as RAT field of FAB. 

BLN - Length of the XAB. 

COD - Type of XAB. (Only FHC XAB type is allowed.) 

EBK — Virtual block number of end-of-file. 

FFB — First free byte in end-of-file block. 

HSZ — Fixed length control header size. Same as FSZ field of FAB. 

LRL — Longest record length. 

MRZ — Maximum record size. Same as MRS field of FAB. 

RFO — File organization and record format. Combines ORG and RFM 
fields of FAB. 

SEN — Starting block number of the file if it is contiguous; otherwise 
field is 0. 
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MACRO-32 
EXAMPLE 

XAB BLOCK: $XABPHC 



BLISS-32 
EXAMPLE 

LOCAL 

XAB_BLOCK I $XABFHC; 
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6.1 Introduction 



The previous chapters have presented the building blocks needed to 
construct a diagnostic prograni that will execute under the VAX Diagnostic 
Supervisor (VDS). This chapter describes the steps required to create a 
VDS diagnostic program. It also specifies all standards and conventions to 
which a diagnostic program must adhere. 



6.2 Program Development Process 
6.2.1 Overview 



Creating a diagnostic program involves several distinct, consecutive phases. 
Each phase is required, and the phases must be entered in the same order 
that they are described here. 



6.2.2 Consultation Phase 



The consultation phase of program development consists of informal 
gathering and exchanging of information relating to the hardware product 
for which the diagnostic program is to be written. This phase should 
begin soon after an engineering or product management group has made a 
commitment to develop a new product. 

Goals of this phase are to formulate a testing strategy for the product (what 
types of diagnostic programs should be developed), identify a few key 
project milestones (dates), and estimate staffing and funding requirements. 

The consultation phase begins before staffing and funding commitments 
have been negotiated. Typically, the result of this phase is a cursory project 
plan. 

Participants will include management and senior technical personnel from 
the engineering group or product line developing the product, the future 
program's user community (generally field service and manufacturing 
personnel), and the diagnostic programming group. 

An important note: If it is desirable for the hardware design of a new 
product to provide aids that will enhance the fault detection of a diagnostic 
program, the diagnostic programming group must then request these aids 
as soon as possible in order to ensure that they will be incorporated into 
the device's final design. Negotiations for design changes to aid diagnosis 
should thus conunence during this phase of the project. 
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Creating a YDS Diagnostic Program 



6.2.3 Planning Phase 



This phase begins after staffing and funding commitments have been 
made. This phase and all following phases are performed by the diagnostic 
program's project leader and his or her staff. 

The goal of the planning phase is to develop a plan for implementation 
of the project. This project plan will include a description of the 
diagnostic program and will specify project goals, schedules, development 
requirements, training requirements, and maintenance requirements. 

The result of this phase is a Diagnostic Engineering Project Plan adhering to 
the format specified by Section 7C3-1.A of the Software Development Policies 
and Procedures. 



6.2.4 Functional Specification Phase 

After the project plan has been completed, the task of defining the 
functional operation of the diagnostic program begins. 

The goal of this phase is to clearly define the functions that the diagnostic 
program will perform. A functional specification must answer the question, 
"What will the program do?" (On the other hand, it should NOT approach 
the question of HOW the function will be implemented.) 

Additionally, a functional specification will include specific statements 
about the program's intended uses and users, plus goals regarding the 
program's performance and run-time parameters. 

The result of the functional specification phase is a Diagnostic Engineering 
Functional Specification that adheres to the format specified by Section 
7C3-2.A of the Software Development Policies and Procedures. 



6.2.5 Design Phase 



The program's design phase may be entered when the functional 
specification phase has been completed. 

The goal of the design phase is to develop a design specification that 
defines the methods that will be used to implement the functionality 
defined in the functional specification. This phase answers the question, 
"How will the program's functionality be provided?" For example, if the 
functional description states that the program will test a certain section of 
the device's logic, then the design specification will describe the algorithm 
to be used to perform the test. 

Some of the methods that may be used to specify designs are: 

• Detailed hierarchy charts 

• Interface specification blocks 

• HIPO diagrams 
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• Structured flowcharts 

• Program Design Language 1 (PDLl) (See below.) 

The result of this phase will be a Diagnostic Engineering Design 
Specification, adhering to the format specified in Section 7C3-3.A of the 
Software Development Policies and Procedures. This document also describes 
PDLl. 



6.2.6 Design Implementation Phase 



After the design has been completely specified, it may be implemented. 
Design implementation is the phase in which coding and debugging occur. 

The schedule on which coding and debugging of the various pieces of 
the program is based depends greatly upon the availability of product 
hardware. Programs that are written for new hardware are typically in the 
process of development concurrently with the hardware itself. Therefore 
it is important to create a schedule for program development that matches 
the hardware development's schedule. 

Implementation of programs for new hardware must often be carried 
out in two stages, referred to as "protot)^e support" and "final product 
support." 

Prototype support involves providing the engineering group responsible for 
the product with a preliminary version of the program. This version will be 
used to help verify the integrity of the hardware design. The engineering 
group will generally expect this version to be ready for use within a matter 
of days after the hardware is "powered up" for the first time. Specific 
requirements for prototype support depend on the particular product. 
These requirements should be specified in the Project Plan and Functional 
Specification. 

Unfortunately, it may be necessary to provide prototj^e support before 
the planning and specification phases described have been completed. 
Therefore, it is important to carefully coordinate all phases of program 
development so that the needs of all users can be met on schedule. For 
example, some portions of the design specification or even the functional 
specification may have to be delayed until debugged code supporting the 
protot)^e hardware has been provided. 

Final product support involves development of the program that will be 
used with the final, error-free version of the hardware product. This is 
the version of the program that will be released for general use. User 
requirements for the final product may be different from user requirements 
for prototype support. Knowledge of the hardware's operation that was 
gleaned by the programmer during development of prototype support will 
aid him or her in creating a program that provides high degrees of fault 
detection and isolation. 

Because hardware development and diagnostic program development 
occur concurrently for new hardware products, it is necessary to carefully 
coordinate the two development processes. Hardware design engineers 
and manufacturing personnel will often desire working versions of the 
diagnostic program before the scheduled completion date. Thus, it is 
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common for diagnostic programmers to provide "prerelease" versions of 
the program before the final program has been completed. A prereleased 
program may or may not provide the full functionality that will exist in the 
final program. 



6.2.7 Design Verification Phase 



Once the final program has been completed, its functionality and operation 
must be assessed to ensure that the program meets all of the functionality 
goals that were originally set, and that it adheres to all applicable operating 
standards (such as using VDS macros properly). Assuring overall program 
quality is performed by following the steps indicated in Section 6.8, Quality 
Assurance. 



6.3 Program Structure 



Chapter 3 and Chapter 4 described all of the required and optional 
components of a VDS diagnostic program. Since all VDS diagnostic 
programs are made up of the same basic components, it is useful to 
arrange these components in the same order and format in the source code 
of every program. This will aid program maintainers by ensuring a large 
measure of consistency from one program to the next. 

In all diagnostic program sources, program components should be divided 
into a series of source modules. There should be a "header module" and 
one or more "test modules." 



6.3.1 Header Module 



The header module contains all of the tables used by the VDS, the 
initialization, cleanup, and summary routines, plus any routines used 
globally by the diagnostic program. Components of the header module 
should be arranged in the following order: 

1 Module cover page (copyright statement, title and author, and 
maintenance history) 

2 Functional description of module 

3 Declarations of libraries and BLISS require files 

4 User-defined macro definitions 

5 Symbol definitions 

6 Diagnostic header ($DS_HEADER) 

7 Dispatch table ($DS_DISPATCH) 

8 Statistics table ($DS_BGNSTAT, $DS_ENDSTAT) (optional) 

9 Section names declaration ($DS_SECTION) 

10 Device mnemonics list ($DS_DEVTYP) 
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11 ASCII text: 

a. Register and bit names for $DS_CVTREG calls 

b. Other ASCII strings 
C. Error message strings 

12 Initialization code ($DS_BGNINIT, $DS_ENDINIT) 

13 Cleanup code ($DS_BGNCLEAN, $DS_ENDCLEAN) 

14 Summary routine ($DS_BGNSUMMARY, $DS_ENDSUMMARY) 

15 Error reporting routines ($DS_BGNMESSAGE, $DS_ENDMESSAGE) 

1 6 Other (optional) global subroutines, including interrupt service routines, 
condition handlers, and so on. 

Note: If a program has many global routines and data structures, they should be 
placed in a separate module. 



6.3.2 Test Modules 



Each test module will contain one or more tests. The number of tests 
modules and the number of tests per module are unrestricted. Each test 
module should be formatted as follows: 

1 Module cover page (cop3n:ight statement, title and author, and 
maintenance history) 

2 Functional description of module 

3 Declarations of library and require files 

4 User-defined macro definitions 

5 Symbol definitions 

6 Section names declaration ($DS_SECDEF) 

7 For each test in module: 

a. Test name ($DS_SBTTL) 

b. $DS_BGNTEST 
C. Test header 

d. For each (optional) subtest in test: 

— Subtest header 

- $DS_BGNSUB 

— Subtest code 

- $DS_ENDSUB 

e. $DS_ENDTEST 
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6.3.3 Module Templates 



Template files have been created to help the programmer follow the above 
formats. There is a header module template and a test module template. 
Each template contains the program-independent fields of each program 
component. The programmer simply fills in the program-dependent 
fields of each module. These templates are named HEADER. MAR and 
TEST.MAR for MACRO-32, and HEADER.B32 and TEST.B32 for BLISS-32. 
The templates are reproduced in Appendixes A and B. 



6.4 Program Documentation 



6.4.1 Introduction 



A diagnostic program should be considered to be made up of two 
parts: the code and the docimientation. Each of these parts is of equal 
importance. Documentation should NEVER be thought of as auxiliary to 
the code, to be hurriedly added at the end of the project if time permits. 
The best documentation is that which is developed before and during code 
development. 

Diagnostic program documentation serves two purposes: 

• Users of diagnostic programs probably refer to and depend on program 
documentation more than users of any other software. This is because 
identification of hardware failures requires a very exact understanding 
of what function is being performed by a particular section of code and 
which areas of the hardware circuitry are likely to be activated to carry 
out that function. It is sometimes necessary for the program user to 
read the program's listing files to see what signals are being activated 
within a test or subtest. 

• As is the case with any software product, program maintenance is 
usually performed by persons other than the product's author. Those 
who must enhance, correct, or otherwise update a diagnostic program 
depend on the documentation for understanding the program's 
function, design, and implementation. 

Documentation for VDS diagnostic programs consists of the following three 
parts: 

• A documentation file containing hardware requirements, operating 
instructions, emd functional descriptions of the program's tests 

• Source code documentation providing detailed functional descriptions 
of every test, subtest, routine, and line of code 

• "Help" files that the user can access with the VDS HELP command, 
and that summarize the program's operating instructions 
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6.4.2 Documentation File 

The documentation file will be distributed with the diagnostic program. 
The documentation file for program EVXYZ will be called EVXYZ.DOC. 
A template for the documentation file is available in both RUNOFF and 
non-RUNOFF formats. A reproduction of the template can be found in 
Appendix C. 

The documentation file will contain the following information: 

1 Cover page 

The cover page contains identification information such as the 
program's name, release date, and maintainer, along with copjnight 
and disclaimer statements. 

2 Table of contents 

3 Abstract 

The abstract is a short description of the program, summarizing 
information found in later sections of the document. This section 
should identify which types of hardware will be tested, and should also 
state the program level ^evel 2R or level 3). 

4 Hardware requirements 

This section lists the minimum hardware required for the program to 
execute, plus any optional hardware. Include special connectors or 
other special hardware required by the program. 

List the processor types with which the program is compatible. Do 
NOT make generalized statements, such as "all VAX processors," 
since the program may not be executable on future processors. 

5 Software requirements 

List the software required, including the VAX Diagnostic Supervisor. 
Any auxiliary data files should be included here. 

6 Prerequisites 

This section should list the program's hardcore requirements; that 
is, the hardware that must be operating properly in order for the 
diagnostic program to correctly diagnose faults on the hMdware being 
tested. 

7 Operating instructions 

In most cases, the VAX/DS Diagnostic Supervisor User's Guide should be 
the only reference needed for operating instructions. 

a. Options 

If the progreun has special instructions (such as using a user-defined 
command language), that information shovild be provided in this 
section. 

b. Event Flags 

If any user-controllable event flags are used by the program, they 
should be listed. 
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Program functional description 

a. Program overview 

This is a general functional description of the program. The 
program's purpose and testing strategy should be included. 

b. Program size 

The load time and run-time memory requirements should be 
specified. Include memory required by any auxiliary data files. 

C. Program run times 

The execution time of each program section is listed here. If a 
QUICK mode is provided, also include its execution time. 

d. Run-time d3mamics 

Indicate how the program allocates resources during execution 
time. Include both memory and device allocations. Specify the 
mimimum buffer space needed. 

©. Fault detection 

Describe the fault coverage (include percentage) and error 
resolution of which the program is capable. 

Include sample error messages, if error reporting routines are used. 

f . Performance during hardware failures 

Indicate how the program will handle unexpected exceptions 
resulting from hardware failures, power failure, and the like. 

g. Program applications 

List the uses for which the program was designed, such as 
manufacturing, customer services, engineering, and customers. 

h. Test descriptions 

For each test, include: 

— A functional description of the test 

— The step-by-step flow of the test 

— Debug aids contain hints to the program user about what 
should be looked at next if the test fails. This is very important 
for logic tests. 

Maintenance history 

Each time the program is updated, the update must be described here. 
The description must include the date of the change, the program's 
version number, and the programmer's name. 
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6.4.3 Source Code Documentation 



6.4.3.1 Diagnostic Codes 

Each diagnostic program released by DIGITAL is assigned a "diagnostic 
code" that uniquely identifies it. Codes for VAX diagnostic programs 
consist of five characters, the first of which is E. The code is assigned by 
the Release Engineering group. 



6.4.3.2 IVIodule Names 

For the diagnostic program with the diagnostic code EVXYZ, the header 
module should be named EVXYZO.MAR if it is a MACRO-32 program, or 
EVXYZ0.B32 if it is a BLISS-32 program. Test modules should be named 
EVXYZl.MAR (or .B32), EVXYZ2.MAR (or .B32), and so on. 



6.4.3.3 {Module Cover Page 

Each module must have a cover page. The cover page will include: 

1 Module and program names, including version numbers (see above). 

2 Cop5^ight statement 

3 Module abstract 

4 Author 

5 Maintenance history. Each time the module is updated, the update 
must be described in the maintenance history. The description must 
include the date of the change and the module's version ntunber. 

The format of the cover page is illustrated in the header module template 
example contained in Appendix A. 



6.4.3.4 Test and Subtest Prefaces 

Each test and each subtest must possess a preface. Prefaces for tests and 
subtests must contain the following information: 

1 Test description 

This will contain a detailed description of what is being tested and how 
the test is implemented. 

2 Assumptions 

List assumptions being made about the state of the hardware before 
the test is executed. For example, if this test will not function properly 
unless certain parts of the hardware are good, list those parts. 

3 Test steps 

In this section list the test steps. A pseudo language is very useful for 
this purpose. 

4 Errors 

Provide a detailed description of all errors reported by this test. 
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5 Debug 



This section should provide information that might be helpful to 
someone attempting to determine the cause of a hardware error. For 
example, there might be a statement of the form "If error number X is 
reported, then Y might be broken." 

The format of test and subtest prefaces is illustrated in the test module 
template in Appendix B. 



6.4.3.5 Subroutine Preface 

Each subroutine must possess a preface. Subroutine prefaces must contain 
the following information: 

• Functional description 

This must be a detailed description of what function the routine performs 
and how the function is performed. 

• Calling sequence 

Indicate how the routine is to be called. For example: 

CALLS #4, ROUTINE or CALLG ARGPTR, ROUTINE 
or BSBW ROUTINE 
or Entered via exception vector 

• Inputs 

List all input parameters that are explicitly passed to the routine. 
Explicitly passed input parameters are those pushed onto the stack 
before a routine is called. (In BLISS-32, explicit input parameters are 
those that are listed in parentheses after the routine name.) 

• Implicit inputs 

List all input parameters that are not explicitly passed on the stack. 
This list will include ANY variable referenced by the routine but not 
defined locally in the routine and not passed explicitly. For example, 
parameters passed in registers are implicit inputs. 

Note: Use of implicit inputs should be kept to a minimum. They adversely 
affect program maintainability and routine transportability. 

• Outputs 

List all output parameters that are explicitly passed back to the caller. 
Explicitly passed output parameters are those that are: 

• Pushed onto the stack by the routine, or 

• Stored into locations whose addresses were explicitly passed to the 
routine. 

• Implicit outputs 

List all output parameters that are implicitly reharned to the caller. 
Implicit output parameters are ANY variables that are modified by the 
routine but were not explicitly passed to the routine. For example, if 
a variable stored in a register is updated, that variable is an implicit 
output. 
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Note: Use of implicit outputs should be kept to a minimum. They adversely 
affect program maintainability and routine transportability. 

• Completion codes 

Indicate all completion codes that could be returned by this routine. If 
the routine passes along completion codes received from subordinate 
subroutines, these codes must also be listed. Also indicate how the 
completion code is passed. (Placing the code in RO is the standard 
method.) 

• Side effects 

List here any actions taken by this routine that could affect the 
operation of other routines. Examples are initializing data structures or 
altering the state of global flags. 

Also, if the routine places the hardware in some unusual or 
indeterminate state, indicate that here. 

• Registers used 

Identify the purpose of each general purpose register used by the 
routine, so anyone reading the code can quickly determine the 
functions of the registers. 

The format of a routine preface is illustrated in the header module template 
of Appendix A. 



6.4.3.6 Source Code Comments 

It is extremely important that the source code be accurately commented. 
Comments within the source code can take three forms: 

• Block comments are used to identify major functions within routines. 

• Group comments are within blocks of code delimited by block 
comments. They are useful when you emphasize a command on 
the page. 

• Line comments are those which appear at the end of each line of 
the program. It is extremely important that line comments appear 
following every MACRO-32 instruction. 

Examples of these forms follow: 

• Block Comments 

MACRO-32 
<skip> 

;++ 

; This is a block comment. It begins at the left-hand margin 
; and extends fully across the page. 

<skip> 

BLISS-32 

<skip> 

!++ 

! This is a block comment. It begins at the left-hand margin 

! and extends fully across the page. 

! — 

<skip> 
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Group Comments 



MACRO- 3 2 

This is a group comment. It is indented the same amount as 
the code being commented, and extends fully across the page. 

BLISS-32 



! This is a group comment. It is indented the same amount as 
! the code being commented, and extends fully across the page. 



! 

! Explain what the IF-THEN-ELSE statement will do. 

IF . . . THEN .... 
ELSE 

BEGIN 



! Explain what the REPEAT-UNTIL loop will do. 
I 

REPEAT 

UNTIL . . . ; 

END; 

• Line Comments 



Clear the data buffers. 



15$: 



CLRL R6 

CLRL W"GOOD_DATA[ R6 ] 

CLRL W^ BAD_DATA [ R6 ] 

AOBLSS #16, R6, 15$ 



Clear buffer pointer 

REPEAT 

Clear longword of good data buffer 
Clear longword of bad data buffer 
Increment pointer and branch back 

UNTIL entire buffer is cleared 



Compare expected and received data, one longword at a time. If 
they do not match, store the expected and received values in the 
good data buffer and bad data buffer, respectively, so they can be 
printed later. 



MOVL 
MOVL 
MOVL 
CLRL 
CLRL 



4(AP), R2 
8(AP), R3 
12 (AP), R4 
Rl 
R5 



Put byte count in R2 . 

Put address of received data in R3. 

Put address of expected data in R4. 

Clear error count. 

Clear buffer pointer. 
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These examples illustrate several concepts: 

• Every MACRO-32 instruction has a comment. 

• It is useful to indicate structured programming constructs where 
applicable. Notice the REPEAT-UNTIL construct in the example. 
IF-THEN-ELSE, WHILE-DO, CASE constructs, and so on, can be 
flagged similarly, enhancing readability. Capitahze keywords and 
indent comments within a construct. 

• Comments provide usehil information. For example, the last comment 
in the last example says, "Clear buffer pointer." It does not say "Clear 
R5," which would be useless to anyone reading the code. 



6.4.4.1 Description of Help Files 

A help file is a text file that is referenced when the VDS HELP command 
is used. Text within the file is displayed to the user. Arguments specified 
with the HELP command are used to determine which portions of the text 
to display. 

A help file must be provided for every diagnostic program. For program 
EVXYZ, the help file must be named EVXYZ.HLP. A user can reference 
this file by typing "HELP EVXYZ". 

The purpose of a diagnostic program's help file is to provide the program 
user with a quick reference source that will summarize the program's 
unique characteristics. Information contained in a help file should include: 

• A program abstract 

• ATTACH procedures 

• A list containing the name and function of each program section 

• Descriptions of devices not supported by the VDS (devices for which 
p-table descriptors reside in the diagnostic program instead of in the 
VDS) 

• A list containing the number and use of any user-selectable event flags 
referenced by the program 

• A description of the program's "quick mode" operation 

• Descriptions of tests requiring manual intervention 

• The format of the program's sununary message, if one exists 



6.4.4.2 Creating Help Files 

Help files consist of keywords and associated text. Keywords are used 
by the VDS to locate the proper text to display. For instance, if a user 
typed HELP EVXYZ SECTIONS, the VDS would search the help file 
named EVXYZ.HLP for the keyword "sections," and then display the text 
following that keyword. There are two types of keywords, referred to as 
"numbered ke3words" and "qualifier keywords." 
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6.4.4.2.1 Numbered keywords 

Each numbered keyword is preceded by a number from 1 through 5. This 
number indicates the keyword's level. Level 1 is the highest level, and 
is used to indicate the file's main topics. Keywords with larger numbers 
are considered to be subtopics of those with smaller numbers. If the file 
contains a level 1 keyword followed by several level 2 keywords, followed 
by another level 1 keyword, the level 2 keywords between the first and 
second level 1 keywords are subtopics of the first level 1 keyword. If the 
second level 1 keyword was followed by another set of level 2 keywords, 
they are subtopics of the second level 1 keyword. 

The level number must be the first character of a new line. There must be 
one or more spaces or tabs between the level number and the keyword. 

When the user types a HELP conunand, the VDS will display the text 
following the specified keyword. It will also display the keywords (but not 
the text) of the next-lowest level subtopics associated with the specified 
keyword. For example, suppose a portion of a help file consisted of the 
following: 



1 SECTIONS 

Program EVXYZ contains the following sections. Type 

HELP EVXYZ SECTIONS section-name 

for details on a particular section. 

2 DEFAULT 

(Text describing DEFAULT section.) 

2 MANUAL 
(Text describing MANUAL section. ) 

2 READ_TESTS 
(Text describing READ_TESTS section.) 

2 WRITE_TESTS 
(Text describing WRITE_TESTS section.) 

1 ATTACH 



If the user typed "HELP EVXYZ SECTIONS", the follomng would be 
displayed: 

SECTIONS 

Program EVXYZ contains the following sections. Type 
HELP EVXYZ SECTIONS section-name 

for details on a particular section. 
Additional information available; 
DEFAULT MANUAL READ_TESTS WRITE_TBSTS 

Any time a topic is specified with a HELP command, the VDS displays the 
text associated with the topic and lists the subtopics (keywords with next 
higher level number) associated with the topic. 

All of the subtopics of a topic are listed directly underneath the topic in the 
help file. Thus, all the level 3 subtopics associated with a level 2 keyword 
would directly follow that level 2 keyword. 
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In the above example, suppose the user typed, "HELP EVXYZ SECTIONS 
DEFAULT". The VDS would display the text associated with the level 2 
keyword "default," and then would list any level 3 ke3rwords that follow 
the text for "default." (The sample help file above does not associate any 
level 3 ke)w^ords with "default.") 



6.4.4.2.2 Qualifier keywords 

It is unlikely that a diagnostic program's help file will require qualifier 
keywords, since they are only used to indicate command line qualifiers. 
They are not preceded by a level number; instead, they begin with the 
slash (/) character. However, a level number is implicitly associated with a 
qualifier keyword; that number is one greater than the number specified in 
the most recently specified numbered ke3?word. That ke3mrord should be 
"Qualifiers". This is illustrated in the following example: 



1 START 

Execute a previously loaded image. 

Format : 

START [qualifiers] 

2 Qualifiers 
/SECTION : section-name 

Select a program section to be executed. 
/TEST:first!last 
Select a range of tests to be executed. 



The slash (/) character must be the first character of a new line. The 
keyword must immediately follow the slash (/). Following the ke5mford 
there may be an additional string, as in /QUAL:string. 

Note: If one qualifier keyword directly follows another, with no text in between, 
the second qualifier keyword will be treated as part of the text for the first. 
This is useful for qualifiers of the form /qual and /NOqual. 



6.4.4.2.3 Text 

Text must immediately follow the ke3Tvord with which it is associated. 
Ke)?words must start on a new line. Each line of the text must be indented 
one space from the left margin. Text associated with level 1 keywords 
should not extend beyond column 65. Text associated with keywords of 
any other level should not extend beyond column 60. The text is more 
easily readable if it does not exceed the length of the display screen (no 
scrolling should occur). 



6.4.4.3 Contents of Help Files 

Help files for diagnostic programs must contain the following level 1 
keywords and associated text: 

1 ATTACH — Describe the attach procedures for the program. That 
is, list the set of ATTACH commands that are necessary to create the 
proper lirJcs from the imit under test to the processor. 
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2 DEVICE — Under this keyword, include a level 2 ke5w^ord for every 
device tested by the diagnostic program. Under each level 2 keyword, 
provide either of the following: 

a. For devices with p-table descriptors contained in the VDS, the 
text should state, "Type HELP DEVICE device-type for device 
description." 

b. For devices with p-table descriptors contained in the diagnostic 
program, provide a device description similar to the device 
description that is obtained from t)^ing "HELP DEVICE device- 
type." 

3 EVENT — List any user-selectable event flags referenced by the 
program and describe their function. 

4 HELP — This text should contain an abstract of the program. The text 
associated with the HELP keyword is displayed when a user types 
'HELP EVXYZ' without including a keyword. In other words, this is the 
default kejrword. 

5 QUICK — Describe the operation of the program when the QUICK flag 
is set. 

6 SECTIONS — List and describe each section of the program. Be sure 
to include the DEFAULT section. If a MANUAL section exists, clearly 
detail the actions that must be performed by the user. 

7 SUMMARY — If the program contains a summary routine, provide an 
explanation of the information displayed by that routine. 

The above keywords must appear in every help file. Other ke5nvords 
should be added to provide information on unique program characteristics. 
The keywords must be placed in the help file in alphabetical order. 

A sample help file is provided in Appendix D. 



6.5 Diagnostic Program Considerations 
6.5.1 Run-Time Environments 



One of the main purposes of the VAX Diagnostic Supervisor, as stated in 
Chapter 2, is to insulate the diagnostic program from the various runtime 
environments that exist for diagnostic programs. 

Thus, if all of the rules, guidelines, and conventions described in this 
manual are followed, any diagnostic program written should be capable 
of executing in any of the run-time environments under which diagnostic 
programs are expected to run. 

Possible run-time environments for VDS diagnostic programs include (but 
are not limited to): 

• User mode 

• Standalone mode 

• Automated Product Test (APT) 
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• Remote Diagnosis (APT/RD) 



6.5.2 Error Message Formats 



As stated in Chapter 3, error messages are displayed by invoking the 
$DS_ERRxxxx services. Error messages consist of three levels. They should 
adhere to standard formats. 

The format of the first message level (the message header) is controlled by 
the VDS. 

The formats of the second and third message levels are controlled by the 
programmer. These parts of the error message are constructed with the 
error-reporting routines called by the $DS_ERRxxxx services and delimited 
by $DS_BGNMESSAGE and $DS_ENDMESSAGE macros. 

When error-reporting routines are constructed, messages should be 
formatted as follows: 

• Invalid contents of a register. 

A message that reports invalid contents of a register should indicate the 
expected contents, the actual (received) contents, and an exclusive-OR 
(XOR) of the expected and received values. Mnemonics of bits set in 
the XOR value should be displayed. Indicate the radix of all values 
displayed. 

Example: 

EXPECTED; 5068 (X) 
RECEIVED: 0000 (X) 
XOR: 5068(X) ;TIE,SAE,RIE,MSE,MAINT,FUNC=READ 

• Reporting data comparison errors for buffers 

When data comparison errors are detected in data transfer buffers, the 
error message should include: 

— The base address of the failing device 

— The address of the buffer 

— The size of the data transfer 

— The number of comparison errors 

— The buffer address and contents of all bad data 
Example: 



Device base address 


60010500(X) 




Expected 


buffer address 


OEIO(X) 




Received 


buffer address 


lOlO(X) 




Transfer 


size 


256 words 




Words in 


error 


4 




Address : 


Expected : 


Received: 


XOR: 


OE104 


1010 


1000 


0010 


OEllO 


1010 


1000 


0010 


OEICO 


1010 


1000 


0010 


OEIFO 


1010 


1000 


0010 



If there is a large number of errors, only display the first eight. 
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Register dumps 

When dumping the contents of a set of registers, list the registers 
in order of address. Display the register mnemonic, the register's 
contents (and radix), and the bit mnemonic for each set bit. 



Example: 



RPCSl 

RPWC 

RPBA 

RPDA 

RPCS2 



144270(0) 
777710(0) 
001000(0) 
001001(0) 
040203(0) 



; SC , TRE , DVA, RDY , FUNC=WRI TECHECK 



; TRACK=2 , SECT0R=1 
;WCE,0R,UNIT=3 



(etc.) 



6.5.3 Volume Verification 



All diagnostic programs that write onto magnetic media must provide 
a mechanism to ensure that a customer's database is not inadvertently 
destroyed. 

Some disks provide for a portion of the medium (called "maintenance 
tracks") to always be reserved for diagnostic purposes. If a diagnostic 
program writes only on the maintenance tracks, the customer's database 
will not be affected. 

If a device being tested does not provide maintenance tracks, or if the 
diagnostic program does not limit itself to only using the maintenance 
tracks on a device that does provide them, the entire medium must be 
protected; a method must exist for verifying that the medium loaded in the 
device under test may be written. 

Thus, for devices that do not provide maintenance tracks, diagnostic 
programs must check the volume name of a storage medium before 
executing any tests that will write on that medium. By convention, media 
that contain no stored data, and therefore are available for the writing of 
test patterns by diagnostic programs are named SCRATCH. 

Volume verification must take place in a program's initialization code. 
The program must read the storage medium's home block to determine 
the medium's volume name. (Refer to the FILES-11 On-Disk Structure 
Specification for a description of the home block's format.) If the volume 
name is SCRATCH, the medium may be used and testing may begin. If 
the volume name is an5rthing other than SCRATCH, the program must 
ask the user (via the $DS_ASKLGCL system service) if it is acceptable 
to use the medium. If the response is "no" (the user does not wish the 
medium to be used), then the program should issue a $DS_ABORT call. 
A DEFAULT RESPONSE MUST BE PROVIDED FOR THE $DS_ASKLGCL 
SERVICE, AND THE DEFAULT MUST BE "NO." This will ensure that 
if the OPERATOR flag is cleared and a nonscratch medium has been 
mistakenly placed in the unit under test, then the medium will not be used. 
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The volume verification code should only be executed the first time through 
the initialization code (use the $DS_BPASSO or $DS_BNPASSO macro). 
Otherwise, the user would have to respond to the $DS_ASKLGCL question 
for every program pass. 

Note: Previous editions of this guide have indicated that, when aslcing the user 
if it is acceptable to use a nonscratch medium, the user prompt passed 
to the $DS_ASKLGCL service must begin with a null character. This 
null will force the VDS to check the user terminal for a response to the 
question, even if the program is being run by a command file (script). (If 
the program is being run by a command file, all responses are obtained 
from the command file unless the prompt string begins with a null.) 

This is not good practice, because it forces limitations onto the user 
regarding how the program may be executed. It should be the user's 
decision whether a question's response is to be fetched from a script or 
from the terminal, not the programmer's decision. Therefore, prompt 
strings should never be preceded with a null character. (Refer to the 
VAX/DS Diagnostic Supervisor User's Guide for a description of command 
files.) 



6.5.4 Long Silences 



A long silence is a long period of time in which there is no communication 
between the diagnostic program and the user. Sometimes long silences are 
good and sometimes they are not. 

A long silence is good when the diagnostic program is running for a long 
period of time, either because the program's execution time per pass is 
long or because a large nmnber of passes has been selected by the user. 
If the user's terminal is a hardcopy terminal, long silences save paper and 
decrease the risk of the unattended, jammed printer scenario; i.e., printer 
jams and halts which cause the diagnostic to hang indefinitely since no 
attendant is present to restart it. 

On the other hemd, a long silence is bad when a user is present at the 
termiiial, monitoring the program's progress. In this case, the user would 
like to be kept abreast of the program's status diuring long executions in 
order to be assured that the program is not hung. If a long silence occurs, 
the only way a user can monitor program progress is to type a control-C, 
then SHOW STATUS, then CONTINUE. Thus, a diagnostic program must 
have the capability of both eliminating and providing long silences. 

To eliminate long silences in programs with long execution times per pass, 
the program should cause a message to be displayed at least once per 
minute. An AST routine may be used for this purpose. The message 
should be a simple, succinct indication to the user that program execution 
is progressing properly. 

To provide for long silences when the user desires them, a means of 
disabling the above-mentioned AST routine should be provided. For 
example, the AST routine should check the stahis of the OPERATOR flag 
(by using the $DS_BOPER or $DS_BNOPER macros) and only print the 
message if the flag is set. 
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6.5.5 Hardware Preparation 



Hardware preparation is the act of setting the device under test in some 
physical state before testing begins. Hardware preparation may include 
setting switches, connecting a cable, loading a special medium into the 
device, and the like. 

Ideally, diagnostic programs should be written so that no hardware 
preparation has to take place. If this is not possible, hardware preparation 
should be kept to an absolute minimum, since it lengthens testing time and 
is a nuisance for the program user. 

All hardware preparation should occur before the program is started. If the 
program requests hardware preparation during execution, it is referred to 
as "manual intervention" (see Section 6.5.6, and is considered to be even 
more of a nuisance. 

If a program detects a preparation error (hardware not set up correctly), the 
$DS_ERRPREP service should be used to report the error. 



6.5.6 Manual Intervention 



The term manual intervention refers to user actions during program 
execution. A program requiring manual intervention is one requiring 
the program user to perform a duty at some point during the program's 
execution. This duty might be as involved as adding a piece of hardware 
to (or removing one from) the system under test, or it might be a simpler 
action, such as tj^ping a response on the terminal. 

Ideally, no diagnostic program should ever require manual intervention, 
because manual intervention complicates the operation of the program 
from the user's point of view. 

If inclusion of manual intervention cannot be avoided, the following rules 
must be followed: 

• If the manual intervention involves any actions other than responding 
to questions at the user terminal, the tests that require these actions 
must be placed in a program section called MANUAL. Examples of 
such actions are setting a write-enable switch, connecting a cable, or 
watching patterns generated by a program that tests video display 
terminals. 

Each test within the MANUAL section must use the $DS_BOPER or 
$DS_BNOPER macro to determine if a user is present. If a user is not 
present, the test must call the $DS_ ABORT service. 

• Communication with the user must be performed by using the 
$DS_ASKxxxx macros. 

• If $DS_ASKxxxx macros are included in the MANUAL section, it is not 
necessary to provide default responses. 
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If $DS_ASKxxxx macros are used anywhere other than in tests within 
the MANUAL section, default responses must be provided. If default 
responses are included, and if the user clears the OPERATOR flag, the 
default responses will automatically be used and the user will not have 
to be present. (This is also true for the DEFAULT section.) 



6.5.7 Quick Mode 



Quick mode is a mode of program execution in which the main objective is 
to provide a relatively fast execution time per pass. It is a convenient mode 
to provide in programs having long execution times. It should provide a 
fast pass/fciil testing capability with little or no fault isolation. It will be 
employed when a user wants a quick verification of hardware integrity. 

The decision of whether or not a diagnostic program will provide a quick 
mode is one shared between the programmer and the program's users. 
Specific functions of a particular program's quick mode are also to be 
decided by mutual agreement between the programmer and users. As a 
guideline, if total execution time for one full program pass under normal 
operating conditions is greater than two minutes, you should consider 
including a quick mode in your diagnostic program. 

If quick mode operation is provided, it is to be executed only if the user 
selects it by setting the VDS control flag QUICK. The program will use 
the $DS_BQUICK or $DS_BNQUICK macro to determine the state of the 
QUICK flag. 

Use caution to determine which functions of the diagnostic program will 
not be utilized in quick mode. The program must be documented so that 
the user will understand the exact functional differences between normal 
and quick modes, since frequently intermittent errors will surface only 
while running under normal (non-quick) mode. 



6.5.8 Naming Symbols 



To maintain consistency between diagnostic programs, it is important 
to obey certain conventiorts when creating names for symbols. These 
conventions are as follows: 

• The dollar sign ($) character is included in all publicly defined s)rmbols 
located in the VDS and in all other system level software provided 

by DIGITAL. To differentiate private symbols (those available only to 
the program in which they are defined) from public symbols, private 
symbols should not include the dollar sign ($) character. Since all 
sjnubols defined in diagnostic programs are private, the dollar sign ( $ ) 
should never be used. 

Note: There is one exception to this rule; since p-table descriptors are 
public, their names should include dollar signs. See Section 3.2.3, 
P-Table Descriptors, for details and examples. 

• To determine the characters allowed in a s)mibol name, and the 
maximum length of a s)m[ibol name, refer to the reference manual 
for the language in which the program is being written. 
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• Global variable names are of the form: 
Gt_variablename 

where "t" is a letter indicating the variable type (see Table 6-1). 

• Global arrays are of the form: 
A_arrayname 

• Structure field names are of the form: 
structure_t_fieldname 

where "t" is a letter indicating the variable type (see Table 6-1). 

• Entry points to global routines having nonstandard calls are of the 
form: 

entryname_Rn 

where registers RO through Rn are not preserved by the routine and 
therefore must be saved by the caller. 

• When naming bits and bit fields in hardware registers, use the bit 
mnemonics specified in the hardware documentation. 

Table 6-1 contains letters used for data t3^es. 
Table 6-1 Letters Used to Indicate Data Types 



Letter Data Type or Usage 

A Address 

B Byte integer 

C Single character 

D Double precision floating 

E Reserved to DIGITAL 

F Single precision floating 

G General value 

H Integer value for counters 

I Resen/ed for integer extensions 

J Reserved to customers for escape to otfier codes 

K Constant 

L Longword integer 

M Field mask 

N Numeric string (all byte forms) 

O Reserved to DIGITAL as an escape to other codes 

Packed string 

Q Quadword integer 

R Reserved for records (structure) 

S Field size 



P 
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Table 6-1 (Cont.) Letters Used to Indicate Data Types 



Letter 


Data Type or Usage 


T 


Text (character) string 


U 


Smallest unit of addressable storage 


V 


Field position (assembler); field reference (BLISS-32) 


w 


Word integer 


X 


Context dependent (generic) 


Y 


Context dependent (generic) 


z 


Unspecified or nonstandard 



Some examples of S3mibol names are: 

A_RP_REG - Address of storage array for RPxx controller registers 

RP_REG_L_RPDS - Offset RPDS into array RP_REG 

GW_ByTi_COUHT - Address of global word containing byte count 

6.6 Linking a Diagnostic Program 

Before a diagnostic program is released, it must be linked as a "system 
image," using the command line: 

S LINK/SYSTEM=-512 EVXYZl, EVXYZ2, . . . 

where EVXYZl, EVXYZ2, and so on, are the source modules for program 
EVXYZ. 

If the s3mibolic debugger for diagnostic programs (VDSDEBUG) is to be 
used during program development, another linking procedure must be 
used. Refer to the VAK Diagnostic Debugger User's Guide for a description of 
that procedure. 

6.7 Debugging a Diagnostic Program 

Two facilities are available in debugging diagnostic programs. 

The VDS command language provides several commands that are 
useful for debugging programs. Commands are available for examining 
and altering memory locations within the diagnostic program, setting 
breakpoints, and "single-stepping" through the program. Refer to the 
VAX/DS Diagnostic Supervisor User's Guide for details. 

More debugging capabilities are provided by the VAX Diagnostic Debugger 
(VDSDEBUG). This is a separate program that can run under the VDS 
in conjunction with a diagnostic program. It provides such features as 
breakpoints, watchpoints, queue traversal, referencing program locations by 
their sjmtibolic names, plus examining and depositing contents of progreun 
locations as nimieric data, character strings, or MACRO-32 instructions. 
Refer to the VAX Diagnostic Debugger User's Guide for details and operating 
instructions. 
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6.8 Quality Assurance 



6.8.1 Quality Requirements 



All diagnostic programs must meet certain quality standards. Quality 
standards must be met in all of the following areas before a program will be accepted 
as a usable product: 

• Documentation quality 

The diagnostic programmer must provide accurate, detailed 
documentation that gives both users and maintainers all the information 
they will need to perform their jobs. Documentation must adhere to 
the guidelines spelled out earlier in this chapter. 

• Functional quality 

The program must provide all of the functional capabilities contained 
in the functional specification. 

• Operational quality 

The program must operate in accordance with the rules established in 
this manual. 



6.8.1.1 Documentation Quality 

Following is a list of the documentation that must be provided with every 
diagnostic program: 

• Documentation file 

The documentation file must adhere to the format presented in 
Appendix C. 

• Map file 

For program EVXYZ, the map file EVXYZ.MAP produced by the linker 
must be provided. 

• Listing file 

For program EVXYZ, the listing file produced by the MACRO-32 
assembler or BLISS-32 compiler must be provided. For MACRO-32 
programs, a cross-reference table must be included. Within the 
listing, the guidelines spelled out in Section 6.4.3, Source Code 
Documentation, must be followed. 

• Help file 

A help file must be provided. It must match the format presented in 
Section 6.4.4, Help Files. 



6.8.1.2 Functional Quality 

The program developer must ensure that all functions described in the 
program's functional specification have been properly implemented. 
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6.8.1.3 Operational Quality 

To ensure the execution quality of a diagnostic program, the following steps 
must be performed. It is strongly suggested that you perform steps 2-6 in 
the order shown): 

1 Load and normal start. 

a. Load the VDS. 

b. Issue the proper ATTACH and SELECT commands. 

c. Load and start the program with the LOAD and START commands 
or the RUN command. 

d. The program should execute without errors and stop after one 
program pass. 

2 For EACH SECTION of the program, the following should be 
performed: 

a. Trace mode 

Issue the SET TRACE command, then START. Check that test 
numbers and trace messages coincide with program documentation 
for the section being executed. 

b. Multiple passes 

Execute the section again, specifying a pass count of at least 10. 

3 For each test of the program, the following steps must be performed: 

a. Reverse order testing 

Execute each test, one at a time, starting with the highest-numbered 
test and ending with test number 1. Allow each test to complete 
one pass. 

b. Multiple loop-on-test 

Execute each test individually, specifjang a pass count of at least 
10. 

C. Multiple loop-on-subtest 

Execute each subtest of each test individually, specif}ang a pass 
count of at least 10. 

d. Control-C response 

For each test, start the test and type control-C. A response to 
the contrpl-C should occur within three seconds. When the VDS 
prompt is displayed, type CONTINUE. The program must continue 
from where it was interrupted and must successfully complete the 
pass. 

e. Event flags 

Check that all event flags are used only as indicated by the 
program's documentation. 
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f . Power off 

Shut off the power for the device under test. The program must 
display a message stating that the device is without power. 

g. Write Protection 

Write-protect the device under test. Tests that write to the device 
should display messages indicating that the device is write- 
protected. 

h. Offline 

Place the device off-line. The program should state that the device 
is off-line. 

i. Minimum hardware configuration 

Set up a hardware configuration that matches the minimum 
hardware configuration specified in the functional specification. 
All tests must execute on this configuration. 

j. Maximum hardware configuration 

Set up a hardware configuration that matches the maximum 
hardware configuration specified in the functional specification. 
All tests must execute on this configuration, and all units of the 
device under test must be tested. 

k. Module extender board 

Place each logic module of the device under test on an extender 
board, one at a time, and verify that each test will execute 
successfully. 

I. Transportability 

Repeat all of the steps in this section on every VAX processor t)^e 
on which the program is supposed to run. 

m. Marginal testing 

If the program has been specified to be executed successfully under 
marginal conditions (voltage, timing, and so on), execute each test 
under these conditions. 

n. Error reporting and loop-on-error 

— Make sure that no $DS_EERxxxx macros are ever executed 
when the cleanup code is run (tj^ing ABORT will cause the 
cleanup code to be run). 

— Set the LOOP and HALT flags. This will cause every error 
reporting macro ($DS_ERRxxxx) to be executed. This can be 
accomplished either by causing hardware failures on the device 
under test or by temporarily patching the program. 
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For EVERY $DS_ERRxxxx macro, do the foUowiiig: 

CLEAR the lEl, IE2, and IE3 flags. 

Make sure that all error messages are printed, and that they 
are of the proper format (see Section 6.5.2, Error Message 
Formats). 

Make sure that the entire message has been printed before 
the DS > prompt is displayed. 

Clear the IE3 flag. 

Type CONTINUE, and make sure that a loop begins 
executing. 

The $DS_ERRxxxx macro should be reexecuted, but this 
time the third level of the error message should not be 
displayed. 

When the DS > prompt appears, clear the IE2 flag. 

Type CONTINUE. 

The $DS_ERRxxxx macro should be reexecuted, but this 
time the second and third levels of the error message 
should not be displayed. 

Clear the lEl flag. 

Type CONTINUE. 

The $DS_ERRxxxx macro should be reexecuted, but this 
time none of the error message should be displayed. 

Set the lEl flag and clear the HALT flag. 

Type CONTINUE. 

Allow the loop to execute several more times. 

The following step must be performed for the DEFAULT section. 

• No operator 

Clear the OPERATOR flag, then execute the DEFAULT section for 
one pass. The program must execute successfully, and the user 
must not be required to t5^e any characters on the terminal or 
perform any other form of manual intervention. 

The following additional steps must be performed for programs that 
execute in standalone mode: 

• Memory Management on 

Turn memory management on and execute each test for several 
passes. Each test should execute successfully unless the program 
should not be executed with memory management turned on, in 
which case the program should abort without errors. 
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• Invalid address 

Using the ATTACH command, specify an incorrect device address. 
The program should display a message indicating that an invalid 
address has been specified. 

• APT compatibility 

To verify that the program will execute under the APT run-time 
environment, run the program under APT for eight hours. 

The following step must be performed for programs that execute in 
user mode. Make sure that all units are properly deallocated after the 
diagnostic program has finished. Issue the following VDS and VMS 
commands in order: 

ATTACH device-name 

SELECT device-name 

RUN program-name 

Type control-C 

ABORT 

T3qpe control-Y 

SHOW DEVICE 

None of the devices that were tested, used for error logging, or made 
use of in any way by the diagnostic program should be still allocated. 



6.8.2 Automated Quality Assurance 



In order to aid the programmer in determining the quality of a diagnostic 
program, the VDS provides an automated quality assurance feature, called 
Auto-QA. This feature will automatically perform some (but not all) of the 
quality assurance checks listed above. 

Auto-QA is invoked by including the /QA qualifier with the RUN or 
START command. Operating instructions for Auto-QA are described in the 
VAX/DS Diagnostic Supervisor User's Guide. 

Following is a list of the quality assurance checks performed by Auto-QA. 
Note that Auto-QA only checks the DEFAULT program section. Quality 
assurance of other program sections must be performed manually. 

1 Normal Start Check 

This check will perform a normal load and execution of the diagnostic 
program with the TRACE flag set. 

The program must make an error-free pass, printing out the normal 
trace messages and terminating with End-of-Pass. If the program does 
not execute an error-free pass, an appropriate QA error message will 
be printed. The trace messages must be visually checked by the user. 

This check also makes sure that the DEFAULT section does not request 
input from the user. (The OPERATOR flag is cleared.) 
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This check is equivalent to the following sequence of VDS commands; 

DS> CLEAR FLAG ALL 

DS> SET FLAG TRACE 

DS> RUN diagnostic-program-name 

DS> CLEAR FLAG TRACE 

2 Multiple Passes Check 

This check will execute 10 passes (by default) of the diagnostic 
program. The program must make 10 error-free passes and terminate 
after the tenth pass. If this does not happen, an error message will be 
printed. 

The number of passes executed by the diagnostic program can be 
changed by the user. 

This check is equivalent to the following VDS command: 

DS> START/PASS! 10 

3 Infinite Loop-On-Test Check 

This check will execute each test in the diagnostic program's DEFAULT 
section 100 times (Isy default). The diagnostic must execute each test 
the given number of times, it the diagnostic does not execute properly, 
an error message will be printed. 

The number of times each test is executed can be changed by the user. 

This check is equivalent to the following VDS commands: 

DS> START/PASSllOO/TESTlljl 
DS> START/PASS: 100/TESTi2: 2 



DS> START/PASS! XOO/TESUn J n 

where "n" is the highest numbered test in the DEFAULT section. The 
tests are executed in ascending order. 

4 Infinite Loop-On-Subtest Check 

This check will execute each subtest in each of the tests in the 
diagnostic program's DEFAULT section 100 times (by default). The 
program must loop on each subtest the given nimiber of times. If the 
program does not execute properly, an error message will be printed. 

The number of times each subtest is executed can be changed by the 
user. 
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This check is equivalent to the following Supervisor commands: 

DS> START/PASS: 100/TEST: 1 ; 1/SUBTEST; 1 
DS> START/PASS! 100/TEST: 1: 1/SUBTEST: 2 



DS> START/PASS: 100/TEST: l:l/SUBTEST:ml 
DS> START/PASS: 100/TEST: 2 :2/SUBTEST;l 
DS> START/PASS: 100/TEST: 2 :2/SUBTEST:2 



DS> START/PASS: 100/TEST: 2 :2/SUBTEST:m2 



DS> START/PASS : 100/TEST : n : n/SUBTEST : 1 
DS> START/PASS : 100/TEST ; n : n/SUBTEST : 2 



DS> START/PASS : 100/TEST : n : n/SUBTEST : mx 

where "n" is the highest-numbered test in the DEFAULT section, and 
"mx" is the number of subtests in test "x." 

The tests and subtests are executed in ascending order. 

Run Individual Tests in Reverse Order Check 

This check executes the tests in the diagnostic program's DEFAULT 
section in reverse order. This check ensures that a test does not 
depend on results from a previous test, and that each test is a 
standalone entity. If the diagnostic program does not execute properly, 
an error message will be printed. 

This check is equivalent to the following VDS command: 

DS> START/TEST:n:n 
DS> START/TEST ;n-l:n-l 



DS> START/TEST: 1:1 

where "n" starts at the highest numbered test in the DEFAULT 
section, and descends to the first test. That is, the tests are executed in 
descending order. 
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A.I Header Module Template for Macro-32 Programs 

This is a template to aid in the development of the header module of a 
diagnostic program that will run under the VAX Diagnostic Supervisor 
(VDS). It is not intended to be a tutorial for writing the program. 

Areas that must be deleted or replaced by the programmer are enclosed 
within matching sets of triple asterisks. 

Areas that may be optionally modified are enclosed within matching sets 
of double asterisks. 

Comments marked with one asterisk are for informational purposes and 
should be deleted. 
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.TITLE 


•** PRO 


GRAM NAME *** 


. IDENT 


/Ol/ 




.LIST 


MEB 




.NLIST 


CND 




. PSECT 


HEADER, 


LONG, NOWRT 



CHANGE ALIGNMENT TO PAGE FOR DEBUG 
.DEFAULT DISPLACEMENT, WORD ;* CHANGE THIS TO LONG FOR DEBUG 

COPYRIGHT (C) 1983 

DIGITAL EQUIPMENT CORPORATION, MAYNARD, MASSACHUSETTS 01754 

THIS SOFTWARE IS FURNISHED UNDER A LICENSE FOR USE ONLY ON A SINGLE 
COMPUTER SYSTEM AND MAY BE COPIED ONLY WITH THE INCLUSION OF THE 
ABOVE COPYRIGHT NOTICE. THIS SOFTWARE, OR ANY OTHER COPIES THEREOF, 
MAY NOT BE PROVIDED OR OTHERWISE MADE AVAILABLE TO ANY OTHER PERSON 
EXCEPT FOR USE ON SUCH SYSTEM AND TO ONE WHO AGREES TO THESE LICENSE 
TERMS. TITLE TO AND OWNERSHIP OF THE SOFTWARE SHALL AT ALL TIMES 
REMAIN IN DEC. 

THE INFORMATION IN THIS SOFTWARE IS SUBJECT TO CHANGE WITHOUT NOTICE 
AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL EQUIPMENT 
CORPORATION. 

DEC ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF ITS 
SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DEC. 

++ 
FACILITY: VAX DIAGNOSTIC. 

ABSTRACT: *** Short description of program. *** 

ENVIRONMENT: VAX DIAGNOSTIC SUPERVISOR. 

AUTHOR: *♦* NAME DATE *** VERSION 01. 

MODIFIED BY: 



.PAGE 

. SBTTL DECLARATIONS 

INCLUDE FILES: 

.LIBRARY \SYS$LIBRARY!DIAG.MLB\ ; VAX FAMILY DIAGNOSTIC LIBRARY. 
** Declare programmer-defined libraries here. 
* (Libraries are searched in reverse to the order listed.) 

MACROS: 

*** USER MACROS (OPTIONAL). *** 

EQUATED SYMBOLS: 

$DS_BGNHOD *** ENVIRONMENT *** 

$DS_DSSDEF GLOBAL ; SUPERVISOR SERVICE ENTRY VECTORS 

;*** USER EQUATED SYMBOLS *** 
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.PAQE 

.SBTTL PROGRAM HEADER DATA BLOCK. 
++ 
FUNCTIONAL DESCRIPTION: 

THE PROGRAM HEADER DATA BLOCK CONTAINS THE PARAMETERS WHICH 
ALLOW THE DIAGNOSTIC SUPERVISOR TO CONTROL THE PROGRAM. 
THE DIAGNOSTIC SUPERVISOR LOOKS FOR THE HEADER INFORMATION 
BEGINNING AT VIRTUAL ADDRESS 200 (HEX). 



$DS_HEADER <***PROGNAME***>, REV=01, UPDATE=0, NUNIT=**1** 
.SBTTL DISPATCH TABLE. 



THE DISPATCH TABLE IS A COLLECTION OF ADDRESSES GENERATED AT THE 
BEGINNING OF EACH TEST AND GROUPED TOGETHER INTO A CONTIGUOUS 
LIST BY THE LINKER, THIS IS DONE BY DEFINING A PSECT CALLED 
DISPATCH. 



$DS_DISPATCH 

.PAGE 

.SBTTL PROGRAM GLOBAL DATA SECTION. 
.PSECT DATA, LONG 
++ 
FUNCTIONAL DESCRIPTION: 

*** ALL DYNAMICALLY MODIFIED DATA SHOULD BE PLACED IN THIS SECTION. ♦** 
*** THIS IS THE ONLY PSECT WHICH WILL NORMALLY BE WRITE ENABLED. *** 



+ 
STATISTICS TABLE. 

$DS_BGNSTAT 
$DS~ENDSTAT 



;*** OTHER GLOBAL DATA (OPTIONAL). *** 
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.PAGE 

.SBTTL PROGEW^ TEXT SECTION. 
++ 
FUNCTIONAL DESCRIPTION! 

THIS SECTION CONTAINS ALL OF THE DATA STRUCTURES THAT ARE MADE UP OF 
CHARACTER STRINGS. 



+ 
PROGRAM SECTION NAMES. 

$DS_SECTION <*** SECTION NAMES ***> 

+ 
DEVICE MNEMONICS LIST. 

T_DEVICE: 

$DS_DEVTYP <*** DEVICES ***> 

+ 
NAMES OF DEVICE REGISTERS AND BIT MNEMONICS 

**♦ ASCII NAMES OF DEVICE REGISTERS AND THEIR BITS (OPTIONAL) FOR *** 
*** USE WITH THE $DS_CVTREG MACRO ROUTINE. *** 

+ 
FORMATTED ASCII OUTPUT STATEMENTS. 

*** MESSAGES TO THE OPERATOR, ETC. (OPTIONAL). *** 
+ 



STRINGS USED TO REPORT ERRORS 
*** ERROR REPORT MESSAGES. (OPTIONAL) ♦** 
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.PAGE 

.SBTTL INITIALIZATION CODE. 
++ 
FUNCTIONAL DESCRIPTION. 

THIS ROUTINE WILL BE EXECUTED AT THE BEGINNING OF EACH PASS. 
*** DESCRIPTION OF YOUR ROUTINE. *** 

CALLING SEQUENCE; 

THE DIAGNOSTIC SUPERVISOR CALLS THIS ROUTINE WITH A CALLG 
INSTRUCTION. 

INPUT PARAMETERS: 

** NONE ** 
IMPLICIT INPUTS; 

** NONE ** 
OUTPUT PARAMETERS: 

** NONE ** 
IMPLICIT OUTPUTS; 

** NONE ** 
COMPLETION CODES! 

** NONE ** 
SIDE EFFECTS! 

** NONE ** 



$DS_BGNINIT 
.*** DEVICE INITIALIZATION CODE. *♦* 
$DS ENDINIT 
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.PAGE 

• SBTTI. CLEAN-OP CODE. 
++ 
FUNCTIONAL DESCRIPTION! 

THIS ROUTINE IS EXECUTED AT THE COMPLETION OF THE LAST PROGRAM PASS. 
*** DESCRIPTION OF YOUR ROUTINE. *** 

CALLING SEQUENCE! 

THE DIAGNOSTIC SUPERVISOR CALLS THIS ROUTINE WITH A CALLG 
INSTRUCTION. 

. INPUT PARAMETERS! 

S 

** NONE ** 

IMPLICIT INPUTS! 

** NONE ** 
OUTPUT PARAMETERS! 

** NONE ** 
IMPLICIT OUTPUTS! 

** NONE ** 
COMPLETION CODES! 

** NONE ** 
SIDE EFFECTS! 

** NONE ** 



$DS_BGNCLBAN 
;*** DEVIci "SHUT-DOWN" CODE. *** 
$DS ENDCLEAN 
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.PAGE 

• SBTTL SUMMARY RBPORT CODE. 
++ 
FUNCTIONAL DESCRIPTION: 

THIS ROUTINE ISSUES A SUMMARY REPORT UPCttI REQUEST FROM THE 
OPERATOR OR WHEN A $DS_SUMMARY_G CALL IS MADE. 
*** DESCRIPTION OF YOUR ROUTINE. *** 

CALLING SEQUENCE: 

THE DIAGNOSTIC SUPERVISOR CALLS THIS ROUTINE WITH A CALLG 
INSTRUCTICMI. 

INPUT PARAMETERS: 

** NC«E ** 
IMPLICIT INPUTS: 

** HONE ** 
OUTPUT PARAMETERS: 

** NONE ** 
IMPLICIT OUTPUTS: 

** NONE ** 
COMPLETION CODES: 

** NONE ** 
SIDE EFFECTS: 

»* NONE ** 



$DS_BGNSUHHARY 
;*** SUMMARY REPORT CODE. (OPTIMIAL) *** 
$DS ENDSUHHARY 



A-7 



Template for the YDS Diagnostic Program Header IModule 



.SBTTL GLOBAL SUBROUTINES. 

.*** OPTIONAL GLOBAL SUBROUTINES, SUCH AS ERROR REPORTING ROUTINES, 
INTERRUPT SERVICE ROUTINES, CONDITION HANDLERS, ETC. 

++ 
FUNCTIONAL DESCRIPTION: 

CALLING SEQUENCE: 

** NONE ** 
INPUT PARAMETERS: 

** NONE ** 
IMPLICIT INPUTS: 
** NONE ** 
OUTPUT PARAMETERS: 

** NONE ** 
IMPLICIT OUTPUTS: 

** NONE ** 
COMPLETION CODES: 

** NONE ** 
SIDE EFFECTS: 

** NONE ♦* 
REGISTERS USED! 
** NONE ** 



$DS_ENDMOD 
.END 
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A.2 Header Module Template For Bllss-32 Programs 

This is a template to aid in the development of the header module of a 
VAX diagnostic. It is not intended to be a tutorial for writing the program. 

Areas that must be deleted or replaced by the programmer are enclosed 
within matching sets of triple asterisks. 

Areas that may be optionally modified are enclosed within matching sets 
of double asterisks. 
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%TITLE '*** title *•*' 

MODULE *** module neune *** ( i 

IDENT - "Ol-OO" 

) - 

BEGIN 

I++ 

1 COPYRIGHT (c) 1983 BY 

J DIGITAL EQUIPMENT CORPORATION, MAYNARD, MASS. 

J 

I THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE USED AND COPIED 

I ONLY IN ACCORDANCE WITH THE TERMS OF SUCH LICENSE AND WITH THE 

! INCLUSION OF THE ABOVE COPYRIGHT NOTICE. THIS SOFTWARE OR ANY OTHER 

I COPIES THEREOF MAY NOT BE PROVIDED OR OTHERWISE MADE AVAILABLE TO ANY 

I OTHER PERSON. NO TITLE TO AND OWNERSHIP OF THE SOFTWARE IS HEREBY 

I TRANSFERRED. 

1 

I THE INFORMATION IN THIS SOFTWARE IS SUBJECT TO CHANGE WITHOUT NOTICE 

1 AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL EQUIPMENT 

I CORPORATION. 

1 

1 DIGITAL ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF ITS 

1 SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DIGITAL. 

! 

I~ 

I++ 

I FACILITYj VAX- 11 DIAGNOSTIC 

I 

I 

I ABSTRACTi *** abstract *** 

I 

1 

J ENVIRONMENT: VAX-11 DIAGNOSTIC SUPERVISOR 

I 

1 

1 AUTHORS *** your name ***, DATE; *** date ***, VERSION: VOl.O 

I 

I MODIFIED BYj 

1 

I — 
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%SBTTL 'Declarations' 

1++ 

I TABLE OF CONTENTS! 

1 — 

FORWARD ROUTINE 

*** routine names *** ; 

!++ 

I EXTERNAL DECLARATIONS: 

1 — 

EXTERNAL ROUTINE 

*** routine names *** ; I In module... 

1++ 

! INCLUDE FILES: 
I — 
*** Declare user-defined libraries and "require" files here *** 
LIBRARY 'SYS$LIBRARY! STARLET'; I VMS MACRO LIBRARY 

LIBRARY 'SYS$LIBRARY!DIAG'; 1 VAX DIAGNOSTIC FAMILY LIBRARY 

1++ 

r MACRO DEFINITIONS: 

1 — 

MACRO 

•** OPTIONAL USER-WRITTEN MACROS *** %; 

!++ 

I DIAGNOSTIC SUPERVISOR MACROS: 

1 — 

$DS_BGNMOD (ENV - *** environment ***); 

SDS^DISPATCH 

$DS~DSSDEF 

$DS~DSADEF 

1++ 

I PROGRAM SECTION NAMES: 

I — 

$DS_SECTI0N (*** section names ***); 

1++ 

1 DEVICE MNEMONICS LIST: 

1 — 

$DS_DEVTYP (STRINGS - (*** device types ***), 

~ ADDRESSES » (*** addresses of PT-desc ***)); 
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%SBTTL 'Program Header Data Block' 

++ 

FUNCTIONAL DESCRIPTION: 

! The program header data block contains the parameters which 

! allows the Diagnostic Supervisor to control the program. 

! The Diagnostic Supervisor looks for t"he header information 

I beginning at virtual address 200(HEX). 

I 

$DS_HEADER (PNAME ='*** program name ***', 
REV = 1, 
UPDATE = 0, 
NUNIT = *** number of units ***); 

%SBTTL 'Program Global Data Section' 

!++ 

! FUNCTIONAL DESCRIPTION: 

I 

!*♦* ALL DYNAMICALLY MODIFIED DATA SHOULD BE PLACED IN THIS SECTION. *** 
I 

! — 

!++ 

1 DEVICE REGISTER CONTENTS TABLE 

$DS_BGNREG 
$DS_ENDREG 

!++ 

! STATISTICS TABLE. 

! — 

$DS_BGNSTAT 
$DS~ENDSTAT 

!++ 

! EQUATED SYMBOLS: 

! — 

GLOBAL LITERAL 

*** enter literals *** ; 

++ 

OWN STORAGE: 

GLOBAL 

*** enter variables *** ; 
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%SBTTL 'Program Text Section' 

!++ 

! FUNCTIONAL DESCRIPTION: 

I 

t This section contains all the character strings. 

! 

I 

!++ 

! NAMES OF DEVICE REGISTERS AND BIT MEMONICS: 

1 — 

GLOBAL BIND 

*** ASCII ncimes of device registers and their bits (optional) 
for use with the $DS_CVTREG macro routine *** 

!++ 

! FORMATTED ASCII OUTPUT STATEMENTS: 

I 

*** messages to the operator, etc. (optional) *** 

!++ 

1 STRINGS USED TO REPORT ERRORS 

I 

*** enter statements ***; 

%SBTTL 'Initialization Code' 

!++ 

! FUNCTIONAL DESCRIPTION: 

I 

! This routine will be executed at the beginning of each pass 

1 of the diagnostic . 

! 

! FORMAL PARAMETERS: 

I 

1 ** NONE ** 

! 

! IMPLICIT INPUTS: 

! 

1 *« NONE ** 

! 

! IMPLICIT OUTPUTS; 

I 

! ** NONE ** 

t 

! COMPLETION CODES: 
I 

1 ** NONE ** 

I 

1 SIDE EFFECTS: 
I 

1 ** NONE ** 

t 

! — 

$DS_BGNINIT 
BEGIN 

*** initialization code *** 

END; 

$DS ENDIHIT 
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%SBTTL 'Clean-up Code' 

++ 

FUNCTIONAL DESCRIPTIONj 

The ole«n-up code is executed at the ctanpletion of the last 

program pass. 

*•* Description of your routine goes here. *** 

FORMAL PARAMETERS I 

** NONE *• 
IMPLICIT INPUTS I 

** NONE ** 
IMPLICIT OUTPUTS s 

** NONE ** 
COMPLETION CODES I 

** NONE ** 
SIDE EFFECTS! 

** NONE ** 



$DS_BGNCLBAN 
BEQIN 

*•* cleanup code *** 

END; 

$DS ENDCLBAN 
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%SBTTL 'Sununary Report Code' 

++ 

FUNCTIONAL DESCRIPTION: 

This routine displays a summary report when the operator types 
a SUMMARY command or when a SDS_SUMMARY call is issued. 
*** Description of the summary routine goes here. *** 

FORMAL PARAMETERS! 

** NONE ** 
IMPLICIT INPUTS: 

** NONE ** 
IMPLICIT OUTPUTS: 

** NONE ** 
COMPLETION CODES: 

** NONE ** 
SIDE EFFECTS: 

** NONE ** 



$DS_BGNSUMMARY 
BEGIN 

*** summary code *** 

END; 
$DS_ENDSUMMARY 
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1 *** Optional global subroutines, such as error reporting routines, 
! interrupt service routines, condition handlers, etc, should 
! be placed here. *** 

%SBTTL 'Global Subroutines' 

!++ 



FUNCTIONAL DESCRIPTION: 



! FORMAL PARAMETERS: 
! 

! ** NONE ** 

I 

1 IMPLICIT INPUTS: 

! 

1 ** NONE ** 

1 

! IMPLICIT OUTPUTS: 

J 

! ** NONE ** 

1 

! COMPLETION CODES: 

! ** NONE ** 

1 

! SIDE EFFECTS: 

I 

I ** NONE ** 

I 

! REGISTERS USED: 
J 

! %SBTTL 'Summary Report Code' 

!++ 

! FUNCTIONAL DESCRIPTION: 

! 

! 

! 

! FORMAL PARAMETERS: 

t 

1 «* NONE ** 

! 

1 IMPLICIT INPUTS: 

! 

1 «* NONE ** 

I 

! IMPLICIT OUTPUTS: 

! 

I ** NONE ** 

I 

1 COMPLETION CODES: 

I 

1 ** NONE ** 

I 

! SIDE EFFECTS: 
J 

! ** NONE ** 

I 

! REGISTERS USED: 

! 

! ** NONE ** 



$DS_ENDMOD; 

END 

ELUDOM 
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B.1 Test Module Template for Macro-32 Programs 



This is a template to aid in the development of a test module of a 
diagnostic program that will run under the VAX Diagnostic Supervisor 
(VDS). It is not intended to be a tutorial for writing the program. 

Areas that must be deleted or replaced by the programmer are enclosed 
within matching sets of triple asterisks. 

Areas that may be optionally modified are enclosed within matching sets 
of double asterisks. 

Comments that contain only one asterisk are for informational purposes 
and should be deleted. 
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.TITLE *** PROGRAM MODULE NAME *** 

.IDENT /Ol/ ;*** VERSION NUMBER *** 

.LIST MEB 

.NLIST CND 

.DEFAULT DISPLACEMENT, WORD ;* CHANGE THIS TO LONG FOR DEBUG 
++ 
COPYRIGHT (C) 1980 
DIGITAL EQUIPMENT CORPORATION, MRYNARD, MASSACHUSETTS 01754 

THIS SOFTWARE IS FURNISHED UNDER A LICENSE FOR USE ONLY ON A SINGLE 
COMPUTER SYSTEM AND MAY BE COPIED ONLY WITH THE INCLUSION OF THE 
ABOVE COPYRIGHT NOTICE. THIS SOFTWARE, OR ANY OTHER COPIES THEREOF, 
MAY NOT BE PROVIDED OR OTHERWISE MADE AVAILABLE TO ANY OTHER PERSON 
EXCEPT FOR USE ON SUCH SYSTEM AND TO ONE WHO AGREES TO THESE LICENSE 
TERMS. TITLE TO AND OWNERSHIP OF THE SOFTWARE SHALL AT ALL TIMES 
REMAIN IN DEC. 

THE INFORMATION IN THIS SOFTWARE IS SUBJECT TO CHANGE WITHOUT NOTICE 
AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL EQUIPMENT 
CORPORATION. 

DEC ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF ITS 
SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DEC. 
++ 

++ 
FACILITY! VAX DIAGNOSTIC. 



ABSTRACT! *** Short description of this module. *** 
ENVIRONMENT! VAX DIAGNOSTIC SUPERVISOR. 
AUTHOR! *** NAME DATE *** VERSION 01. 
MODIFIED BY! 
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.PAGE 

. SBTTL DECLARAT I ONS 

! + 

! INCLUDE FILES: 



.LIBRARY \SYS$LIBRARY:DIAG.MLB\ ; VAX FAMILY DIAGNOSTIC LIBRARY 
;** List programmer-defined libraries here. 
•«* (Libraries are searched in reverse order.) 



; + 

; MACROS: 



.**« PROGRAMMER-DEFINED MACROS (OPTIONAL). *** 

; + 

J EQUATED SYMBOLS; 

;*** SYMBOLS FOR LOCAL USE AND SUPERVISOR INTERFACE *** 
.*** AND USER EQUATED SYMBOLS (OPTIONAL). *** 

$DS_BGNMOD <*** ENVIRONMENT ***>,TEST=*** NUMBER OF FIRST TEST IN MODULE*** 

$DS CHDEF GLOBAL ; CHANNEL SERVICE SYMBOLS (LEVEL 3) 

$DS~DSSDEF GLOBAL ? SUPERVISOR SERVICE ENTRY VECTORS 

; + 

; PROGRAMMER-DEFINED LOCAL AND GLOBAL STORAGE 



? + 

; SECTION DEFINITIONS: 

$DS SECDEF <*** SECTION NAMES ***> 
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• PAGE 

SDS_SBTTL <*** TEST NAME ***> 
++ 
TEST DESCRIPTION! 

THIS VfILL CONTAIN A BRIEF DESCRIPTION OF WHAT IS BEING TESTED 
AND HOW THE TEST IS IMPLEMENTED. 

ASSUMPTIONS! 

*** ASSUMPTIONS MADE BEFORE THE TEST IS RUN, SUCH AS 

WHAT PARTS OP THE HARDWARE MUST BE FUCTIONING PROPERLY 
BEFORE THIS TEST IS EXECUTED. *** 

TEST STEPS: 

*** DETAILED DISCRIPTION OF THE TEST AND TEST FLOW *** 

1) FIRST STEP, INITIALIZATION 

2) SECOND STEP 

3) THIRD STEP 



ERRORS ! 



*** DETAILED DISCRIPTION OF THE ERRORS DETECTABLE AND REPORTED *** 
ERROR 01 ! 
ERROR 02: 
ERROR 03! 



DEBUG: 



THIS SECTION WILL CONTAIN INSTRUCTIONS ON HOW TO USE THIS 
TEST IN DEBUGGING THE UNIT UNDER TEST. 



$DS_BGNTST <*** SECTION NAMES ***>, ALIGN=ByTE ; * CHANGE THIS TO 

;* PAGE FOR DEBUG 

+ 
BLOCK COMMENTS TO EXPLAIN WHAT A SPECIFIC BLOCK OF CODE 
IS DOING 
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+ 

SUBTEST DESCRIPTION! 

*** BRIEF DESCRIPTION OF WHAT THE SUBTEST CHECKS *** 
SUBTEST STEPS: 

*** DETAILED FLOW OF TEST SEQUENCE *** 

ERRORS! 

*** BRIEF DESCRIPTION OF EACH OF THE ERRORS 
THAT CAN BE DETECTED BY THIS TEST *** 

DEBUG : 

*** HELPFUL HINTS FOR TRACKING HARDWARE FAULTS *** 

$DS_BGNSUB 



; + 

; BLOCK COMMENT 



$DS_ENDSUB 
$DS~ENDTEST 
$DS_ENDMOD 
.END 
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B.2 Test Module Template for Bliss-32 Programs 

This is a template to aid in the development of the header module of a 
VAX diagnostic program. It is not intended to be a tutorial for writing the 
progreun. 

Areas that must be deleted or replaced by the programmer are enclosed 
within matching sets of triple asterisks. 

Areas that may be optionally modified are enclosed within matching sets 
of double asterisks. 
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%TITLE '«** title ***' 

MODULE *** module_naine *** ( 1 

IDENT = '01-00' 

) = 

BEGIN 

!++ 

1 COPYRIGHT (c) 1983 BY 

} DIGITAL EQUIPMENT CORPORATION, MAYNARD, MASS. 

! 

! THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE USED AND COPIED 

! ONLY IN ACCORDANCE WITH THE TERMS OF SUCH LICENSE AND WITH THE 

I INCLUSION OF THE ABOVE COPYRIGHT NOTICE. THIS SOFTWARE OR ANY OTHER 

I COPIES THEREOF MAY NOT BE PROVIDED OR OTHERWISE MADE AVAILABLE TO ANY 

I OTHER PERSON. MO TITLE TO AND OWNERSHIP OF THE SOFTWARE IS HEREBY 

! TRANSFERRED. 

1 

! THE INFORMATION IN THIS SOFTWARE IS SUBJECT TO CHANGE WITHOUT NOTICE 

1 AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL EQUIPMENT 

1 CORPORATION. 

1 

! DIGITAL ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF ITS 

• SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DIGITAL. 

J 

!— - 

1++ 

1 FACILITY: VAX- 11 DIAGNOSTIC 

I 

! 

J ABSTRACT! *** abstract *** 

! 

I 

! ENVIRONMENT: VAX- 11 DIAGNOSTIC SUPERVISOR 

1 

I 

! AUTHOR: *** your name ***, DATE: *** date ***, VERSION: VOl.O 

! 

! MODIFIED BY: 

1 

1 — 

1++ 

! INCLUDE FILES: 

I — 

*** List all prograiraner-defined libraries and "require" files here. *** 
LIBRARY 'SYSSLIBRARY:DIAG'; 

!++ 

1 SUPERVISOR MACROS 

I — 

$D5_BGNM0D (ENV = *** environment ***, 

~ TEST = *** starting test number ***); 
$DS_DSADEF 
$DS~DSSDEF 
$DS~SECDEF (*** section names ***); 

1++ 

t EXTERNAL DECLARATIONS 

! — 

EXTERNAL ROUTINE 

*** routine name *** ; 

EXTERNAL 

*** names *** ; 
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%SBTrL '*** subtitle ***' 
++ 

TEST DESCRIPTION! 



*** This will contain a brief description of what is being tested 
and how the test is implemented. *** 

ASSUMPTIONS : 

*** Assumptions made before the test is run, such as 
which portions of the hardware must be functioning 
properly before this test is executed. *** 

TEST STEPS: 

*** Detailed description of the test and test flow *** 

1) *** First step. Initialization *** 

2) *** Second step *** 

3) *** Third step *** 

ERRORS: 

*** Detailed description of the errors detectable and reported *** 
Error 01: *** description *** 
Error 02: *** description *** 
Error 03: *** description *** 



DEBUG: 



*** This section will contain instructions on how to use this 
test in debugging the unit under test. *** 



$DS_BGNTEST (SECTION = *** section names ***, 
TEST = '*** test name •**'); 

!++ 

! *** Block comment to explain what a specific block 

! of code is doing *** 

I 

BEGIN 
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%5BTTL '*** subtitle ***' 

!++ 

1 SUBTEST DESCRIPTION: 

! 

1 *** Brief description of what the subtest checks *** 
I 

! SUBTEST STEPS: 
! 

*** Detailed flow of test sequence *** 

ERRORS: 

*** Brief description of each of the possible errors detected *** 
! 

! DEBUG: 
1 

I *** Helpful hints for tracking hardware faults *** 
I 

! 
f 

$DS_BGNSUB 

!++ 

! *** Block comment to explain what a specific block 

I of code is doing *** 

1 — 

BEGIN 

*** subtest code *** 

END; 

$DS_ENDSUB 

END; 

$DS_ENDTEST 

$DS_ENDMOD 

END 

ELUDOM 
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File 



This is a template for VAX Diagnostic documentation files. Everything to 
be changed, added, or deleted is enclosed within matching double angle 
brackets, "<<" and "> >". 
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IDENTIFICATION 

Product code: ZZ-< < maindec code, including version > > 

Product name: < < program name > > 

Product date: < < submission date > > 

Maintainer: < < diagnostic engineering group > > 

The information in this document is subject to change without notice 
and should not be construed as a commitment by Digital Equipment 
Corporation. Digital Equipment Corporation assumes no responsibility for 
any errors that may appear in this document. 

The software described in this document is furnished under a license and 
may be used or copied only in accordance with the terms of such license. 

No responsibility is assumed for the use or reliability of software on 
equipment that is not suppUed by Digital or its affiliated companies. 

Cop3n:ight (c) < < first year, current submission year (if different) > > 
by Digital Equipment Corporation. All Rights Reserved. 

The following are trademarks of Digital Equipment Corporation. 

DEC DECsystenri-10 DECSYSTEM-20 

DECUS MASSBUS PDP 

UNIBUS VAX VMS 

< < any additional trademarks > > 

< < Digital logo > > 



Table of Contents 

1.0 Abstract 4 

2 . Hardware Requirements 4 

3.0 Software Requirements 4 

4.0 Prerequisites 4 

5.0 Operating Instructions 4 

5 . 1 Options 4 

5.2 Event Flags 4 

6 . Program Functional Description 5 

6 . 1 Progrsun Overview 5 

6.2 Program Size 5 

6 . 3 Program Run Times 5 

6.4 Run-time Dynamics 5 

5.5 Fault Detection 5 

6.6 Performance During Hardware Failures 5 

6.7 Program Applications 5 

6.8 Test Descriptions 5 

7.0 Maintenance History g 
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C.I Abstract 



< < program abstract; from 3 to 20 lines > > 



C.2 Hardware Requirements 

< < minimum hardware configuration; optional hardware > > 



C.3 Software Requirements 



C.5 



< < software environment, e.g. VAX Diagnostic Supervisor > > 



C.4 Prerequisites 



< < hardware that should be verified before running this program > > 



Operating Instructions 

< < Refer to the VAX Diagnostic Supervisor User's Guide (AA-FK66A-TE) for 
instructions on how to load and start the Diagnostic Supervisor and also 
how to load and execute the programs. The operator must ATTACH and 
SELECT the device < < e.g., KA880 > > before starting this program. > > 



C.5.1 Options 



C.5. 2 Event Flags 



< < any operator options, such as MANUAL section > > 



< < The following event flags are used by this program. > > 

• < < event flag 1 > > 

• < <event flag 2> > 

• << etc. >> 



C.6 Program Functional Description 



C.6.1 Program Overview 

< < purpose, strategy, transportability > > 
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C.6.2 Program Size 

< < names and sizes of all associated files > > 



C.6.3 Program Run Times 

< < quick verify, default, with options > > 



C.6.4 Run-Time Dynamics 



< < memory allocations, side effects, sequence of testing on multiple 
units > > 



C.6.5 Fault Detection 

< < error resolution, error message formats, fault coverage (%) > > 



C.6.6 Performance During Hardware Failures 

< < unsuspected traps, power failure > > 



C.6.7 Program Applications 

< < field service (RD), manufacturing (APT), customers, engineering > > 



C.6.8 Test Descriptions 



< < for each test/subtest, "Test description", "Test steps", and "Debug 
aids" > > 



C.7 Maintenance History 

< < date, version: description of changes > > 
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Below is the help file for the diagnostic program EVKAS. All help files 
should follow the following format: 

1 TESTS 



TEST INST 



TEST INST TEST INST 



1 MOVF 
4CVTBF 
7CVTFB 
10CVTRFL 
13ADDF3 
16MULF2 
19DIVF3 
22 ACBF 
25 TSTD 
28 CVTLD 
31 CVTDL 
34 CVTRDL 
37 ADDD3 
40 MULD2 
43 DIVD3 
46 ACBD 



2 MNEGF 
5CVTWF 
8CVTFW 
11 CMPF 
14SUBF2 
17MULF3 
20 EMODF 
23 MNEGD 
26 GVTBD 
29 CVTDB 
32 GVTFD 
35 GMPD 
38 SUBD2 
41 MULD3 
44 EMODD 



3TSTF 
6CVTLF 
gCVTFL 
12ADDF2 
15SUBF3 
18DIVF2 
21 POLYF 
24 MOVD 
27GVTWD 
30 GVTDW 
33 GVTDF 
36 ADDD2 
39 SUBD3 
42 DIVD2 
45 POLYD 



1 ATTACH 

The CPU must be attached. For more help, t5^e HELP EVKAS ATTACH 
(processor mnemonic). 

When running in Stand-Alone mode, only the primary CPU should be 
selected. The SELECT ALL command should not be used after running the 
Autosizer. 

2 KA62A 

DS> ATTACH KA62A HUB KAn (1) (2) 

(1) XMI node Id 7 (node-id) 

(2) FPU Present ?(YES or NO) 

2KA884 

DS> ATT KA884 HUB KAn (1) (2) 

(1) Primary (YES or NO) 

(2) CPU Id (0,1,2 or 3) 
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IHELP 

This program exercises the floating point instructions that can be executed 
in any mode, i.e., non-priviledged instructions. The program is capable 
of running under the Diagnostic Supervisor in either the standalone 
environment or as a user task under VMS. It is also designed to run on any 
member of the VAX family of computers. Currently supported processors 
include the 8840 and 6200. 

1 SECTION 

Sections have been allocated to test certain groups of instructions. For 
more information, type HELP EVKAS SECTION (section name). 

2 F.FLOATING 

Single Precision Floating Point Instructions: 

MOVE, MNEGF, TSTF, CVTBF, CVTWF, CVTLF, CVTFB, CVTFW 
CVTFL, CVTRFL, CMPF, ADDFn, SUBFn, MULFn, DIVFn, EMODF, 
POLYF, ACBF. 

2 DOUBLE 

Double Precision Floating Point Instructions: 

MNEGD, MOVD, TSTx, CVTBD, CVTWD, CVTLD, CVTDB CVTDW 
CVTDL, CVTFD, CVTDF, CVTRDL, CMPx, ADDDn, SUBDn, MULDn, 
DIVDn, EMODx, POLYD, ACBD. 

2 MOVXMNEGX 

All MOVx and MNEGx Single, Double Floating Point Instructions 

MOVE, MNEGF, MNEGD, MOVD. 

2CVTXX 

AH CVTxy and CVTxyz Single, Double, Floating Point Instructions 

CVTBF, CVTWF, CVTLF, CVTFB, CVTFW, CVTFL, CVTRFL, CVTBD 
CVTWD, CVTLD, CVTDB, CVTDW, CVTDL, CVTFD, CVTDF, CVTRDL. 

2 ADDSUBMULDIV 

All ADDxn, SUBxn, MULxn and DIVxn Single, Double Floating Point 
Instructions: 

ADDFn, SUBFn, MULE, DIVFn, ADDDn, SUBDn, MULDn, DIVDn 
2 EMODX 

All EMODx Single, Double Floating Point Instructions: 

EMODF, EMODD 

2 POLYX 

All POLYx Single, Double Floating Point Instructions: 

POLYF, POLYD 

2ACBX 

All ACBDx Single, Double Floating Point Instructions: 
ACBF, ACBD 
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1 EVENT 

Event flags 2 through 6 are active with this program. 

2 FLAG2 

Disables the interval timer interrupting during instruction execution. 

2FLAG3 

Enables the interval timer interrupting while page faulting is also enabled. 

2 FLAG4 

Enables the continuation of a subtest after an error (normally, the subtest is 

aborted). 

2 FLAG5 

Disables the DIVP instruction execution during interval timer interrupting. 

2 FLAG6 

Enables the user to create a custom section of tests by asking what tests 
are to be executed. If this flag is set, the diagnostic prompts the user for 
the test numbers that the user wants executed. When you have finished 
entering, hit Carriage Return to the response for a test number and the 
diagnostic will begin. You may input any number of test numbers. 

IMPORTANT: If you select a particular section and that test number is NOT in the 

section, THE TEST WILL NOT EXECUTE; i.e., SECTION takes priority 
over FLAG6 selections. To obtain a list of the instructions and which test 
executes that instruction, type HELP EVKAS TESTS. 

****** THIS FLAG DOES NOT WORK IF THE OPERATOR FLAG BIT IS 
CLEAR ****** 

1 QUICK 

The QUICK flag disables the execution of the instructions with page 
faulting so that each instruction test case is only executed once for each 
addressing mode combination. 

1 SUMMARY 

The summary report gives an error count by test number. No report is 

generated if there were no errors. 
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bus • 3-20, 4-5 

displaying internal registers of • 4-5 

Interrupts from • 3-23 
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vector field" 5-81 
$ALLOGATE« 3-20,4-2 
Allocate devices • 4-1 , 4-2 
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definition • 4-26 
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